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 decision
  • Provides context
  • Discusses alternatives & opinions

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.

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

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.