documentation.mdwn (2340B)
1 **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. 2 3 * Gets the user started 4 * Allows the user to learn by doing 5 * Ensures the user sees results immediately 6 * Focuses on concrete steps, not abstract concepts 7 8 **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. 9 10 * Solves a problem 11 * Focuses on results 12 * Allows for some flexibility 13 14 **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. 15 16 * Explains a decision 17 * Provides context 18 * Discusses alternatives & opinions 19 20 In some cases, a discussion that is superficially about a single system may contain deeper insights that make it closer to **wisdom literature**. This type of literature may help pass design wisdom from a generation to another. **Textbooks** may also come close to wisdom literature. 21 22 **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. 23 24 * Describes the machinery 25 * References material should be austere and to the point. 26 * Structure the documentation around the code 27 * Do nothing but describe 28 29 Reference guides are particularly crucial for hardware. In software, reference information can be (laborously) derived from the source code or even the binary executable, but similar analysis for microchips requires specialized equipment and can be considerably more complex.