Forums » taskwarrior website »
master user documentation outlines
Added by David Patrick 380 days ago
Paul's documentation has always been good. Amazingly thorough and up do date, especially considering what a moving target task has been, but I think the time has come for another few structural layers.
I think the documentation must be split in two;
hard, dry, complete command reference, organized by programmatic logic on a monolithic page (man-page output)
and
generous usage documentation/ tutorial, laid out in sections, more-or-less in order of typical software usage patterns and learning curve.
| introduction | what is task, what is task not, who task is for, who task is by |
| getting started | getting task installed and configured |
| create, list and complete | the most basic use of task |
| it's a date | date formats, relative dates and recurrences |
| assigning attributes | priority, projects, tags.. |
| search, replace, undo and undelete | how to handle misteaks |
| the search string | how to find exactly what you're looking for |
| lists and reports | how to use and customize the built-ins, and how to make your own |
| import and export data | to or from csv and several other formats |
| interacting with the shell | tab completion, pipes and characters to avoid |
| _appendices |
| best practices and personal productivity |
| command reference/ man pages |
| how-tos |
Advanced usage, rather than being grouped together in a later chapter, should be included at the end of the appropriate section.
Replies
RE: master user documentation outlines - Added by Paul Beckingham 380 days ago
Do the existing man pages (and their online equivalents) already cover the first set?
RE: master user documentation outlines - Added by David Patrick 380 days ago
The existing docs are reasonably comprehensive, and yes, I think the man-page output serves well as command reference, but I have issue with the grouping and layout.
Right now, it is divided between Simple usage, Advanced usage and advanced has many sub-sections. I don't think the outline, as it stands, has a clear flow, with regards to quick look-up, nor natural learning path.
I think the user docs should be clearly sectioned and each section should end with related advanced usage.
Command reference (simply man-page output ?) should be it's own document with no embellishment.