A cheatsheet on Documentation.
This outlines the documentation guidelines for the release of Nataniev projects.
Clarity is better than cleverness
Tutorials are lessons that take the reader by the hand through a series of steps to complete a project of some kind. They are what your project needs in order to show a beginner that they can achieve something with it.
- Gets the user started
- Allows the user to learn by doing
- Ensures the user sees results immediately
- Focuses on concrete steps, not abstract concepts
How-to guides assume some knowledge and understanding, and take the reader through the steps required to solve a real-world problem. They are recipes, directions to achieve a specific end - for example: how to create a web form; how to plot a three-dimensional data-set; how to enable LDAP authentication. How-to guides are quite distinct from tutorials. A how-to guide is an answer to a question that a true beginner might not even be able to formulate.
- Solves a problem
- Focuses on results
- Allows for some flexibility
Explanations can equally well be described as discussions. They are a chance for the documentation to relax and step back from the software, taking a wider view, illuminating it from a higher level or even from different perspectives. You might imagine a discussion document being read at leisure, rather than over the code.
- Explains a choice
- Provides context
- Discusses alternatives & opinions
Reference guides are technical descriptions of the machinery and how to operate it. They are code-determined, because ultimately that's what they describe: key classes, functions, APIs, and so they should list things like functions, fields, attributes and methods, and set out how to use them.
- Describes the machinery
- References material should be austere and to the point.
- Structure the documentation around the code
- Do nothing but describe
- What are you trying to do?
- How is it done today?
- How is your approach different?
- What difference will it make?
- What are the risks and payoffs?
- How much will it cost?
- How long will it take?
- How can we check if it was successful?