[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!

[Zocker1999NET]

(I’m sorry that it took me some time to answer and that this answer is so long. I hope you understand that I am invested into this & other issues because I want to aid TaskWarrior and not because I want to just hate. I love TW and am thankful for having access to the software & its code.)

Roughly citing from Diátaxis, software documentation can be in different forms, depending on their purpose. Diátaxis identifies:

• Tutorial: actionable lesson for learning, intended for newbies
• How-To Guide: actionable, not for learning but for working, intended for competent users
• Reference: technical descriptions, neutral facts, complete, free of distraction & interpretation
• Explanation: provide reasoning & perspective, as answer to the question "why?"

IMO TWs current documentation consists of mostly Tutorial and How-To Guides, mixed with some Explanation in between, with a lack of proper Reference. Tutorials are great for newbies & How-To Guides are great if you find one aligning with your goal, and TW has a lot of that, which btw. is great.

But if you don’t find an aligning How-To Guide, you need Explanation to gain enough understanding, and then Reference to know your possibilities. While Explanation is somewhat easy to maintain (requires changes infrequently), Reference is not because it should be accurate, complete and reliable to be useful.

I see three main problems with the current documentation. First, it lacks a bit of separation between these forms. By this I mean that before clicking on a certain title, it is not clear what kind of documentation I will find.
E.g. the title Command Line Syntax suggests to me that this page mostly is a Reference about the syntax. But IMO it is rather a Tutorial because it contains a lot of explanation and stays ambiguous rather than being authoritative & complete.
Or, looking at the reason why I opened this issue: The hole 3rd-Party Application Guidelines page is a mix of Tutorial, How-To Guide and Explanation. It gives a lot of reasoning, making it hard to read if you only want to know what you should do. But it expects readers to be already experts because it does not explain what 3rd-party devs should do or how they can get there. Linking to other parts of the documentation and providing complete References e.g. for the configuration can help a lot in that case.

Second, the official documentation is split in multiple locations and lacks a lot of usable cross-references. There are, at least, the web documentation, the man pages (e.g. taskrc) and running task help. This is problematic because a) you need at least three different interfaces to access those (your website, a man page renderer and a shell) and b) there is no introduction or similar explaining where users can find which aspect or form of documentation. Hence in a lot of cases, I find myself searching e.g. for urgency-related settings in multiple places.
Also, the web documentation by itself is split into multiple sub-pages and hence is not easily searchable by itself. E.g. I stumble across the setting urgency.inherit and want to know what it exactly does. I might search for it in the Urgency page, but it is not there. So the best I can do is either opening all pages by hand or opening inconveniently an external search engine and search for site:taskwarrior.org "urgency.inherit" in the hope of finding anything.
Having a single-page with all web doc pages & man pages & the task help is a relatively cheap way of improving this.

At last, most "Reference" pages are hard to find and are lacking completeness & authority. E.g. the web page Configuration does not mention that there is a man taskrc. The closest to a reference it mentions is task show, which is not great as it does not contain any description at all. man taskrc contains such descriptions, but is not complete (e.g. urgency.inherit is missing).

[ryneeverett]

Having a single-page with all web doc pages & man pages & the task help is a relatively cheap way of improving this.

IMO, adding a search functionality would be better than giving up on structuring our documentation in pages. Ctrl-F is really not the ideal search engine because you're going to pick up all kinds of cross-references which aren't relevant when you're just trying to learn about a specific concept.

It seems to me that, besides searchability, the second lowest hanging fruit you've identified is more and better cross-referencing. Perhaps a glossary of terminology would be helpful for establishing canonical references to terms/concepts? While consistency and intentional differentiation in the documentation type would be ideal, this might serve as a preliminary step because it would highlight the inconsistencies (and possibly omissions).

Edit: Silly me, I forgot that there is a glossary: https://taskwarrior.org/docs/terminology/. Perhaps we just need to do more interlinking with it?

[djmitche]

I saw a talk by Daniele Procidat at PyCon years ago and was struggling to find the content. Diátaxis is it! I think it's a great way of understanding and structuring docs. And I agree that the TW docs are not up to those standards.

I think you've identified a few key issues:

• Hard for a user to navigate to the type of documentation they need, as they are al intermingled
• Hard for a user to find documentation, as it's accessed via several unrelated means
• Documentation is not up-to-date, as it is somewhat redundant and not always updated together
• There is no comprehensive search functionality

I feel like the first point would require a pretty substantial rewrite -- which is not to say we shouldn't do it!

The second and third points might be addressed by focusing all of the documentation in a single repo (taskwarrior) and using some tooling to make sure it all lines up, so developers can write a piece of reference information once and have it appear everywhere it is required.

The last point could be addressed by better search integration, as @ryneeverett suggests. But we might also consider various LLM integrations. I'm no AI booster, but this does seem like a reasonable use of an LLM, especially one that is privacy-respecting and provides links to authoritative information instead of hallucinating.

[Zocker1999NET]

Thanks. Its great to read that my points came across.

adding a search functionality would be better than giving up on structuring our documentation in pages.

I would also not give up your structuring in pages. I rather would like to also have a variant of the documentation which is automatically rendered into a single HTML or PDF page.
E.g. compare the Debian Users‘ Manual, this is highly structured, and the HTML version is split into these structures. But, for easier search or for offline-use, one can simply download the PDF and go that way. In their case, one can even use plain old grep on the plain text version.
I think making both available should be easy to accomplish & maintain.

[ryneeverett]

I find the offline use case compelling. While it doesn't preclude html/pdf also, getting all the docs into the man pages would be nice. They could be both separate documents and also assembled into a single searchable man page (man task-all?).