Documentation
Here are some scattered thoughts on writing and maintaining documentation. My experience doing this is wholly confined to software development, but I think most of this advice is general enough to make sense in other domains, too.
All text is hypertext.
One thing well
I think good documentation picks a lane and runs there. It doesn’t try to be everything for everyone all at once.
The lanes available:
- Tutorials, learning-oriented (teaching someone to cook)
- How-to guides, problem-oriented (a recipe for cooking a specific thing)
- Explanation, understanding-oriented (historical overview of an ingredient’s cultural importance)
- Reference, information-oriented (an encyclopedia article about an ingredient)
Each of these maps fairly well to an audience:
- Tutorials are for folks who are totally new to a thing
- How-to guides are a step up from tutorials and help you learn idioms and best practices of a space
- Explanation is useful when needing to convey the value of a thing
- Reference is generally for experts who are cozy doing the thing
Know who will be using your documentation, and try to understand how
Information architecture can make-or-break how usable documentation is. In order to create useful documentation you need an understanding for how folks will be interacting with your docs. What will the be looking to accomplish — related to the previous section, know your audiences’ goals.
Grade level is a terrible target
Never worry about “grade level,” instead, focus on how long you want someone to spend reading a thing to understand it.