XXIIVV
Analogies
Analogies11X07

A cheatsheet on Documentation.

This outlines the documentation guidelines for the release of Nataniev projects.

Clarity is better than cleverness unknown

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.

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.

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.

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.

Heilmeier's

  1. What are you trying to do?
  2. How is it done today?
  3. How is your approach different?
  4. What difference will it make?
  5. What are the risks and payoffs?
  6. How much will it cost?
  7. How long will it take?
  8. How can we check if it was successful?

incoming documentation