= 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.