[doc] 3rd-party documentation should become more actionable

[Zocker1999NET]

issue summary

This 3rd-party documentation is actually a great documentation page to have because it increases the chance of 3rd-party software & hooks integrating nicely with each other. But IMO following abstract at the end is not really useful to 3rd-party devs:

Familiarize yourself with the means of forcing color on or off, disabling word wrapping, disabling bulk operation limitations, disabling confirmation, disabling rebuilding the working set, modifying verbosity and so on. There are ways around almost all the restrictions, and while these don’t make sense for regular users, they can be critical for add-on authors.

The warning/content by itself is important. But IMO it is missing important references to actual useful content. So I mean something developers can immediately work with (instead of becoming frustrated, because they now have to read the full documentation, in the hope that the find every possible hurdle).

reasoning / story

To make an example: "disabling rebuilding the working set":

• imagine you want to write a tool
  • your tool will need to regularly export all TaskWarrior tasks
• You are a good dev, you read this phrase in the 3rd-party doc.
  • but it does not say what you should do, nor where you can read more about that.
• So you search on the documentation home page for "working set", hoping to find more infos.
  • but you find no results …
• So you become frustrated & search for it in your default search engine. Then you may find the doc page "ID Numbers".
  • there you finally learn about rc.gc=off

Great. Now you can repeat this steps for at least 5 more points, which is tedious, especially because there is (to my knowledge) no single reference/terminology page to find the right documentation for each point listed in this list.

why it matters?

Because 3rd-party devs can, in theory, just ignore all that stuff. Their code could work for most cases until some "edge case" happens (the ID numbers change while the user did not expect that, suddenly some verbose output is messing up with your code, your code halts because of a seemingly random confirmation question, your code fails because a task title was too long and so wrapped, …).

possible solutions

Each is capable to solve this specific issue by itself. But they could also be combined:

• link to the specific documentation page for each point
• add more "soft references" in the text (like "working set" ~ "ID numbers" ~ "garbage collecting (gc)")
• name the actual action recommended (like rc.gc=off)
• provide a searchable (speak: CTRL+F) page with all references / terminology / …
  • (the current terminology page is not something like that, because e.g. it misses infos about e.g. "confirmations" and "bulk operations")
  • the lazy, but mostly useful, solution is to also render a single HTML/PDF page with the full documentation
    • e.g. Debian provides them as PDFs or TXTs

why I create an issue for discussion instead of doing it myself

• I think I am not familiar enough with this project to know which solutions are to be preferred.
• Each of these solutions has disadvantages in the long run concerning maintenance & staleness.

[djmitche]

We could potentially fix this specific doc issue, but I'm interested in your broader thoughts about how to better document taskwarrior!