The thing is, documentation isn't a monolithic thing --- it really needs to be sub-divided/categorized into subsets which are useful to specific categories of folks working on, or working with, a project:
That does make a huge difference, though I have found you also need to divide by the audiences. There are usually two main audiences that need addressing:
1. The new user. They typically know nothing about the product, not even why it exists. The CTO/CIO bought it and now you have to use it. They need lots of hand-holding and needs concrete instruction. Tutorials and explanations are focused on them so they can build accurate mental models of how the software work.
2. The experienced user. They have a pretty good idea of how the product works, but business requirements have changed in some way and know needs to make adjustments to their processes. Or just needs reminders of less used features. Good how-tos and reference material is vital.
If you don't take care of these things the customer will abandon your product sooner than later.
Agreed, but IMHO it should be layered so one can enter at the highest conceptual level and drill down and back up so there's a continuous flow of understanding.
My experience is that if there's too much documentation for a given representation, a not insignificant number of folks will not read it --- divide and conquer seems to be a workable approach.
What you describe sounds a lot like Diátaxis[1], which is a strategy for writing and organizing technical documentation. It categorizes docs into one of four categories: tutorials, explanations, how-tos, and references.
Category is derived from a fairly simple heuristic: whether the content informs action or cognition, and whether the content serves the reader’s application or acquisition of a skill[2]. I’m a fan and it’s simple enough that most anyone can learn it in an afternoon.
The thing is, documentation isn't a monolithic thing --- it really needs to be sub-divided/categorized into subsets which are useful to specific categories of folks working on, or working with, a project:
https://diataxis.fr/
(originally developed at: https://docs.divio.com/documentation-system/)
divides into 4 types of documentation:
- Tutorials
- Explanation
- How-to Guides
- Reference
My own documentation got much better when I broke it up along those lines.
That does make a huge difference, though I have found you also need to divide by the audiences. There are usually two main audiences that need addressing:
1. The new user. They typically know nothing about the product, not even why it exists. The CTO/CIO bought it and now you have to use it. They need lots of hand-holding and needs concrete instruction. Tutorials and explanations are focused on them so they can build accurate mental models of how the software work.
2. The experienced user. They have a pretty good idea of how the product works, but business requirements have changed in some way and know needs to make adjustments to their processes. Or just needs reminders of less used features. Good how-tos and reference material is vital.
If you don't take care of these things the customer will abandon your product sooner than later.
Agreed, but IMHO it should be layered so one can enter at the highest conceptual level and drill down and back up so there's a continuous flow of understanding.
My experience is that if there's too much documentation for a given representation, a not insignificant number of folks will not read it --- divide and conquer seems to be a workable approach.
2 replies →
What you describe sounds a lot like Diátaxis[1], which is a strategy for writing and organizing technical documentation. It categorizes docs into one of four categories: tutorials, explanations, how-tos, and references.
Category is derived from a fairly simple heuristic: whether the content informs action or cognition, and whether the content serves the reader’s application or acquisition of a skill[2]. I’m a fan and it’s simple enough that most anyone can learn it in an afternoon.
1. https://diataxis.fr/
2. https://diataxis.fr/compass/
You have an interesting commenting style. ~
Lots of sentences occupying an entire paragraph.
Sometimes ending with "~". Usually (always?) your posts end with a question.
You are clearly using some sort of framework for your posts.
Care to elaborate? ~
Please take your slop comments elsewhere. We are trying for something different here on HN.