How do you organize TODOs about the document itself?

[Anrock]

Hello.

I often write specifications, manuals and other documents that explain how something works (or should work when implemented) and how to use it.

Usually its medium-big documents that I'm unable to write up in one go completely. Sometimes I also brainstorm on the go producing multiple variants of something so later on one of them will be chosen, leaving effects consideration comments. Sometimes I'm lost completely and have to do some additional research and experimentation.

I use multiple ways to keep track of such in-progress/TBD things: top level section at the beginning of the document with task lists, %inline comments%, leaving - (?) TBD items or headers and so on.

But none of them feel quite right: top level section is separated from the context, todo items about the document itself are hard to distinguish from implementation plan, inline comments require manual eye-scanning to find and pollute the contents.

I've been thinking on trying to use footnotes. Keep todo items in footnote definitions in one place and put links where some thought is required thus allowing to have one place where concern is defined and multiple places it affects. But after reading footnotes help it seems to be functionally the same with header and links. What's the point then? Is it only useful for exporting to pdfs or other output formats?

So I'm a bit lost with subj question. How do you organize this? Is there an official recommended intended way to do this?

[bendavis987]

It sounds like you want a way to keep track of notes on the document but not in the document itself. You're trying to force it into a header, top section, or footnotes.

If this is correct, why not make a separate document for notes about that document you're working on. You can write links to the specific section you're commenting on like so:

|example
{:path/to/file:123}
{:path/to/file:# Location within that file}
{:path/to/file:** Level 2 heading}
|end

Keep both open in buffers and you should easily be able to toggle between the two.

As for writing multiple variants, try out quote blocks. They're nestable so you should be able to use 1 level for indication that it's in progress. You could write a summary of what you're considering (link to this from your Todo note) then do a level 2 block per variant of the section.

Check out some tutorials for building a second brain. You might see some other tricks like this.