RFC 13 - Todo Notes

[aleksey-rowan]

This is the discussion for RFC 13 - Todo Notes.

[aleksey-rowan]

Using the bracket ([ ]) syntax for track completion has an advantage of searchability. It's always possible to search for [x] or [ ] in a single or across multiple files to check how many tasks have been completed or are left to be done. There are also extensions like Todo Tree that count, highlight and summarize todo items by searching for [x]/[ ] patterns (or other custom patterns).

Using frontmatter variables to track completion and only rendering the [x] as a Text Decorator will make it impossible to manually search for completed tasks and to use extension similar to Todo Tree.

Suggestion

Include the [x]/[ ] patterns (or some other characters or even a ✔) in the task's file name, so it's possible to find them using a simple text search.

<!-- raw markdown -->

- [[proj.[x]-dig-a-hole-[x]]]
- [[proj.[ ]-build-a-cabin-[]]]

Tradeoff

Dendron will need to rename tasks files and all the corresponding reference links as the task's completion status changes.

[kevinslin]

See my response to @ryan-p-randall here -> #1358 (reply in thread)

[jonathanyeung]

• For the section on the Log - where does the log exist? On the task note itself, or the note that references the task note?

• Building upon @aleksey-rowan's earlier comment - I do agree there are some disadvantages to having the - [ ] part only be in the rendered part of the markdown. If someone is on a page with a bullet list of tasks, how does one quickly mark off all of them as completed? They would need to click each wikilink, then update the frontmatter status on each individual note? That feels a bit tedious. Ideally we'd have some sort of two way UI binding - but it seems too fragile for us to try to implement something like that between two separate markdown files.

[kevinslin]

• The log would exist inside the task note itself, as a h2 header inside the note
• We would have a command to mark a task as complete. More discussion on rendering here -> RFC 13 - Todo Notes #1358 (reply in thread)

[SeriousBug]

Perhaps we could get to a good middle ground by using the decoration highlights, but adding integration with Todo Tree. For example, we could automatically add a TODO: note title line to the frontmatter for these notes, which Todo Tree would hopefully pick up. When the note is marked as completed, we can automatically remove that frontmatter property.

[codeluggage]

There's a lot of interesting history in the org-mode world with states stored in the name. Typically you'd have TODO for open items, NEXT for chained items in a GTD style flow (or more advanced chains), CANCELED with a note/reason to differentiate from DONE.

The most interesting part that could be immediately useful for this feature is the ease of formatting these "chains" through the pipe symbol separator. Left side is active, right side is inactive. Using this type of qualifier would also make it very easy for org-mode users to migrate to Dendron, set up for better pod import/export support, and very easy to manage in settings.

Example: "TODO WAITING | DONE CANCELED" giving two active states and two inactive states, where each has a useful connotation.

[simkimsia]

I like the idea of allowing the ability for chained items and dependencies as stated by orgmode

such as https://orgmode.org/manual/TODO-dependencies.html#TODO-dependencies
and https://orgmode.org/worg/org-contrib/org-depend.html

[SeriousBug]

These are both very interesting, thanks for the feedback. Perhaps we could do the same dependency structure through hierarchies, e.g. having a task note with child task notes.

I'm not sure I understand what the chains do. It looks like they are used to configure when timestamps should be inserted to track the tasks history? It's not clear to me how this would apply to the Todo feature in Dendron.

[codeluggage]

The main benefit is to have more than a boolean state that is done: true/false. Chaining them together has various benefits, but the main thing to me is being able to have connotations with the state of a todo that is more than true/false.

I.e. is it done because it was cancelled and should never be done, or because it was completed? And is it not done because you haven't started it yet, or because you're waiting for someone to get back to you?

[simkimsia]

Between chaining and dependencies, I care more about dependencies

Until today when I come across this discussion thread, I have never come across any text based todo management that natively handles task dependencies

So orgmode intrigues me now.

It would be good if dendron joins the club of text based todo management that natively handles task dependencies

Edit:

I realize I didn't explicitly state why dependencies matters to me.

Let me explain.

As a developer often I encounter novel problems which I roughly know how to solve but don't know precisely how to

So while stepping through the problem, I like to document my steps.

There will always be the occasional cul de sac. That's fine. Once I have solved the problem, it would be good to extract out the pure step by step with clear dependencies as a template to run again should the novel problem recurs on second time.

Think of that one problem which you have to open multiple browser tabs on stackoverflow to solve. Then you forgot to document the exact steps which you then need again 10 months later.

My own documentation skills are bad and I haven't been the most success at extracting successful solutions once they are past a certain length of steps.

[ryan-p-randall]

As someone who constantly uses markdown editors on my phone for tasks I keep track of with Dendron files, I really hope the "editing notes outside of VS Code" scenario is kept in mind as we design this feature. If it's possible, I'd recommend not relying too much on VS Code's UI, text decorators, keybindings, or even file names to show task-related information or to make them discoverable. External editors often recognize the - [ ] / - [x] pattern for tasks and will style them accordingly. Using file names seems likely to lead to duplicated or lost files.

I'm not sure what to recommend, so I'll share a description of what I currently do. Hopefully a user story can be productive?

I use Todo Tree with a few different patterns that are also tags in Dendron. I've configured Todo Tree to look for the names of some top-level tags as patterns (like #urgent or #waiting), which makes them show up in the Todo Tree pane.

I'm used to the Taskpaper format of annotating tags, where annotations go in parentheses: @waiting(need Death Star blueprints). Parentheses don't seem to work with Dendron's current tags, but using ; or ? works nicely: #urgent;(he's our only hope). This will show the annotation in Todo Tree and makes sense when looking at the file outside of VS Code. It also won't be interpreted by Dendron as a subtag or entirely different tag than #urgent.

This use of tags also works with sub-tags. If I have tags.waiting.md, tags.waiting.obi-wan.md and tags.waiting.lando.md, I can write #waiting.obi-wan or #waiting.lando and both will show up in Todo Tree under the tag #waiting, with the different people's names visible as annotations.

In my files, I currently enter tasks like this:

- [ ] destroy Death Star #waiting;(need Death Star blueprints)
    - [ ] get plans to Obi-Wan Kenobi #urgent;(he's our only hope) #waiting.obi-wan
    - [x] send R2-D2 to Tatooine #done;(YYYY-MM-DD) 

This lets me see the different annotations in the files themselves, whether in Dendron, the Todo Tree pane, and also in external editors on my phone. I'm not sure if using Dendron's tags like this is the ideal approach to todo notes, but it is at least understandable in external editors.

Perhaps what this user story suggests is that we might want to consider at least two different types of Todo Notes or todo-related behaviors?

One might be a special type of note for projects. Its features could rely more on frontmatter, and be less interoperable with external editors. It might use the decorator trick to show percentage done wherever it's referenced, based on something in the frontmatter, and could also serve as a log.

The second feature might be more for atomic tasks / sub-tasks, and be designed with interoperability in mind? Maybe there can be a Dendron command (like Doctor: fixFrontmatter) that can look for changes or specific strings that are easily entered on other editors, then will update the frontmatter or logs kept on project files? Maybe strings like ;;done or {>>done:YYYY-MM-DD<<} could be entered on lines with tasks in mobile editors, then a Dendron command would apply those changes to the main project note? Just brainstorming potential approaches… 

Basically, I just want to say that I'm thrilled that so many people are thinking about how to use VS Code & Dendron to do something that's difficult with text files! I also really hope that we keep interoperability with non-Dendron tools in mind as the patterns and features develop.

[kevinslin]

Thanks for the detailed explanation and example (as always)! I like the #{name}({description}) pattern - could be a future extension of tags but will save that for another discussion.

For representing todos via decorators vs inline text, maybe we can find a middle ground?

• phase I
  • by default, dendron uses decorators to represent tasks
    • eg. the follow text - [[this is a todo]] will render as - [ ] [[this is a todo]] prio:high
  • we introduce a doctor command that converts task decorations to its string representation
    • when a task note is rendered as an actual string (lets call this a compiled string), we forego rendering the decorator
    • implementation wise, this could be denoted as a tag (eg. - [ ] [[this is a todo]] #nodecorator) - when rendering decorators, we skip lines with that tag
    • when you convert a line to not use a decorator, updating the task note frontmatter will NOT update compiled strings
• phase II
  • we extend the doctor command that updates all compiled task notes
    • this is a manual command but can be run after updating a task to make statuses up to date
  • we introduce an option to auto update compiled task links when the user scrolls to the page
    • what we want to avoid is performing a refactoring operation everytime we update a task, especially since there can be any number of notes that are linked to the current task
    • this option is a compromise - navigating to notes containing compiled task notes are always up to date
• phase {future}
  • task notes can be rendered either as decorators or as compiled strings
  • updating a task note that is rendered as a compiled string will update the text of that note everywhere

[codeluggage]

Would any of this make it possible to show the task as a checkbox in the code/edit view, ala https://github.com/tejasvi/markless? It is one of the only parts I find indispensable, as the [ ] for the task gets lost in a sea of square brackets for me without the checkbox rendering.

[kevinslin]

yes, that is also in the works!

[SR--]

An ability to hide todos on published pages would be good. One can hide lines with HTML comment tags <!--- ... ---> but this kills Todo Tree functionality, highlighting, etc.

[hikchoi]

UX

After using task notes for a week or so now, I feel the need of converting an existing note into a task note.

e.g.)

1. I start with a scratch note where I develop an idea as it naturally comes (amoeba pattern)
2. I get to a point where it becomes an actionable task, at which point I want it to be a task note
3. I run Dendron: Convert to task note, which will add the necessary frontmatter that are missing.
4. A quickpick pops up with the task hierarchy populated so I can move this scratch note into a more sensible location.

Another sort of command that would be nice is a command that prompts you for setting the frontmatter properties specific to task notes.

e.g.)

• Dendron: Set Task Note Status can pop up a quickpick with the available statuses defined in dendron.yml, which you can select to set the status. Same goes for other properties.
  • These commands can take initial value so the user can optionally create keybindings for them
  • These command looks at the current cursor position / selection and see if a task note is selected. If so, the command will run on the selected wikilink to the task note rather than the active document. Otherwise the command runs on the active document.
    • This might confuse the users a bit, so maybe exposing a contextual UI where you can right click and set status could be added as a compromise.

I've read a few prior discussion on exposing more metadata (e.g. status) to the filename. I feel like this goes against the conventional expectation of markdown task lists. I think this problem stems from the fact that we don't have wysiwyg rendering of the notes in VSCode, and have to resort to text decorations to emulate it. Ideally we would not worry about this if we have full control of how it's rendered. But for now my personal opinion is on the conservative side and preserving the conventional way of markdown task lists. Instead, we add tooling around some operations that we lose from rendering text decorations:

• quickly marking off a task
  • I believe my proposed Dendron: Set Task Note Status command (either by command or contextual UI) could solve this.
• Todo tree integration
  • I agree with the middle ground @SeriousBug suggests.

On the enhancement direction of todo notes (special notes in general)

The discussion on storing state in the note name a la org-mode is interesting. We definitely have a lot of users coming from org-mode and this would be a great addition. However, I think the purpose of having a note type system, and implementing a special note type that Dendron natively support is to suggest a best practice. I think it is important that we take note of that and limit what the todo note is capable of. (This is not strictly a point discussed with the note type system RFC, but I have brought this up in the discussion for note indexes here: #1076 (comment), which was where @jonathanyeung suggest we develop the idea of note type system.)

Perhaps we can fully develop this note type (and accompanying commands) so that it offers a best practice experience of the conventional markdown todo note, and separate the concerns of extended power features like supporting org-mode-like features or external integration capabilities to another special note type? This way, we have the freedom to explore complex operations like org-mode's chaining and taskpaper's notations without worrying about how it meshes with the vanilla todo note.

Building a solid foundation around the vanilla todo note type would capture light users and newcomers. Separating a more advanced todo note into a separate note type would make power users happy. Separating the two will simplify the implementation details. Less moving parts on each note type system, less things that could be broken.

Just some of my personal sentiments toward the note type and its future direction. Not necessarily opposed to any of the prior suggestions in this thread; I just think they are on a different scope and perhaps need some separation of concern.

[hikchoi]

Additional thoughts on text decorations

These decorations are VSCode specific, and I think building things around the fact that it exist could bite us in the future when we want to extend beyond VSCode, say, into a web client for example. At that point, any feature that assumed the existence of the text decoration would probably have to re-designed and re-implemented. So I think whatever tooling we decided to add around the todo notes should not take the text decoration too much into account and try to build on top of vanilla markdown. Unfortunately I don't really have an alternative to suggest at this point.

[SeriousBug]

The alternative to text decorators would be to put the actual text with the link to the task note, but that the disadvantage that all linked notes need to be updated every time task state, or any other information on the task changes. This can be especially bad in shared vaults where it will cause noisy commits that are likely to cause conflicts.

[hikchoi]

Yeah, that is the concern I had with it. My point here was that the decorations should be decorations and not a crucial part of how this note type operates. But then we are back to zero with no way to show the metadata of the notes outside the note itself (in the context of having them in another note as a wikilink). So this is me blindly raising a concern for the near-future rather than a suggestion. Probably would not be a big issue if we keep the tooling around note type lean 😅

[kevinslin]

For rendering decorators, moving forward, I see todo notes being implemented using the note type system (we're currently exploring calling it the note trait system, aka rust, because it allows users to add shared behavior to notes).
One of the functions that note traits expose is the ability to generate how a link looks when it is embedded inside a note. You can think of VSCode decorators as being the VSCode implementation of the "todo trait" but that there'll be additional implementations in the future.

[ScriptAutomate]

For tracking purposes and awareness, here are the docs for the evolving Task Notes in the Dendron Docs as this continues to be implemented

[chmac]

First I'd like to quote from a beloved tool nb which takes an interesting approach. Todos are a file, and tasks a markdown - [ ] inside that file. So there's a hierarchy of 2 levels. The done / undone status is tracked as the first ## [ ] Task title inside the markdown document. This hierarchy would be totally compatible with extensions like Todo Tree.

Another really nice aspect of nb is that it uses .bookmark.md, .todo.md and so on to track different types of notes. Does dendron have any plans to do similar? I see that schemas are .schema.yml. Personally I like this approach. I like the idea of being able to build a web client that reads all .todo.md files and lets me see my tasks without vscode / dendron / etc. I know some other vscode extensions also use this approach of targeting only specific files in a repo (like a todo.md file in the root).

Second, I want to second what @ryan-p-randall said. One of the reasons I chose dendron is to be able to combine it with other VSCode extensions. Being able to manage our data (todos and others) with other tools is a huge win. Personally, my dream would be that many PKM systems interoperate on the same data structure, so switching is zero cost. Anyway...

[chmac]

What about tracking the status field in a "todo note" (or is it a "task note") like so:

status: [ ]

Advantages

• Other extensions will find [ ] as a todo
  • If they show the filename, this tells you enough to recognise the task
• The same statuses can be supported in task notes and in "plain tasks" (aka, tasks inline anywhere in markdown)