What nobody tells you about documentation -- Divio blog

notes.md

https://www.divio.com/blog/documentation/

Tutorials

• step-by-step guide
• make sure that it is robust
• Minimum explanation
• Complete a little project

How-to Guides

• How to a achieve a specific goal
• Like a recipe to cook something
• Series of steps
• No explanation

Explanation

• background + context
• goal: understanding of a certain aspect
• different perspectives
• the "why" of things: descision, constraints
• alternatives
• "Explanation should do things that the other parts of the documentation do not. It’s not the place of an explanation to instruct the user in how to do something. Nor should it provide technical describe."

Reference

• accurate and complete
• like an encyclopaedia
• e.g. APIs
• "austere and to the point"
• Links to how-to guides, explanations and tutorials

Example: Structure of Django documentation:

https://docs.djangoproject.com/en/1.11/#how-the-documentation-is-organized