Page MenuHomePhabricator
Paste P10518

what nobody tells you about documentation
ActivePublic

Authored by brennen on Feb 25 2020, 5:10 PM.
= what nobody tells you about documentation =
https://www.divio.com/blog/documentation/
Posits 4 kinds:
- tutorials
- how-to guides
- explanation
- technical reference
I'm already skeptical that there are specifically 4 kinds, but whatever, let's
see where it goes.
"most people try to create good documentation" - counterpoint: no they don't.
"When we learn a new craft or skill, we always begin learning it by doing."
- this emphasis very much lines up with my SparkFun / Adafruit / DigitalOcean
experience.
"Your tutorial must be reliably repeatable."
"Tutorials unfortunately need regular and detailed testing to make sure that
they still work." - I appreciate the emphasis here that documentation requires
_active maintenance_. That's hard even for orgs that really focus on
documentation to build into their process.
"Reference material should be austere and to the point."
"Discussions are less easy to create than it might seem - things that are
straightforward to explain when you have the starting-point of someone’s
question are less easy when you have a blank page and and have to write down
something about it."
"Explanation should do things that the other parts of the documentation do
not."
There are quibbles, but as a framework I can see applying this to my own
software.