Page Menu
Home
Phabricator
Search
Configure Global Search
Log In
Paste
P10518
what nobody tells you about documentation
Active
Public
Actions
Authored by
brennen
on Feb 25 2020, 5:10 PM.
Edit Paste
Archive Paste
View Raw File
Subscribe
Mute Notifications
Award Token
Flag For Later
Tags
None
Referenced Files
F31630626: raw.txt
Feb 25 2020, 5:10 PM
2020-02-25 17:10:14 (UTC+0)
Subscribers
None
= 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.
Event Timeline
brennen
created this paste.
Feb 25 2020, 5:10 PM
2020-02-25 17:10:14 (UTC+0)
Log In to Comment