The overall structure of a document can greatly improve a piece of documentation. If the reader feels like he is always fully orientated in a piece of documentation, the learning experience will be more effective.

Also, a fixed structure can serve as a good starting point for an author, who would otherwise have a hard time trying to figure out where to start when writing some documentation. Of course it's difficult to squeeze different kinds of documentation into one structure, so there should be different structures for different types of documentation (tutorial, how-to, manual...), although synergies should be exploited wherever possible.

Here we will collect the basic elements every piece of documentation needs, no matter if it is a how-to, a tutorial or a manual.

• Title - Quite self-explanatory really, but there are some rules that need to be followed when choosing the title. The author should always try to see the title from a readers point of view to check if it makes sense, even if the subject of the document is not known before. It should be as distinct and short as possible and contain words that a reader would look for when searching documentation on a given subject.
• Purpose-  Begin each doc with a Purpose statement. This statement should tell the reader exactly what this doc will (or will not) cover. This statement should reflect exactly what the user will accomplish by following the steps.
• Prerequisites- two kinds: technical and skill/knowledge - List all technology requirements as well as skills requirements. Link to anything that helps you fulfill those prerequisites. For the user to be able to play along, a "de-facto"-standard must be established. This should be the first paragraph after the title and purpose, so the user does not have to skip back and forth while he should be concentrating on following the document's main focus. The prerequisites section should include the needed packages and their versions, the tools needed to be able to play along, and any other information that the user needs to set up his environment. Documents that belong to a learning trail should be tested on the same Zope/Plone (and additional commonly used packages) versions. Ensuring this should be the job of the documentation team, which can give feedback on problems to the author. We can not expect the authors to test for every possible version, on the other hand we can't expect readers to change their versions after every document in a learning trail.
• Audience- define the intended audience. Who is this for?
  
• Links- any links that may be helpful to completing this task. The documentation team can use that information to decide if the document should be included in a learning trail or if some of the information of those links should be integrated into the document and adjust it accordingly (there should be no need for the author to do that).
  
• Version info
• Tags
  

There are also specific things required for different kinds of documentation, apart from the basics (above) that every piece of documentation should have. These are listed below.

1. Really short bits - how-tos
2. Longer piece - tutorials
3. Collections of resources into a "learning path" - manuals
4. References - lists of fields, widgets etc
   

• tells you how to do one thing and one thing only
• Task Based- a how to should be broken down into steps. These steps should show the reader how to complete one (and only one) task.
  
• Steps- each step should be numbered. Each step should be only one action, no matter how small an action.
  
• Results- for each step, consider including a Result. A Result should tell the reader how the system will react, what they will see, what kind of response the action will cause.
  
• Decision Points- When you come to a step where the reader must make a decision, use an If/Then table (or statement). Example: If you want to do A, go to step X. If you want to do B, go to step Y.
  

Tutorials

At the most basic level, a tutorial is a series of how tos with a bit of context/why information. By following a tutorial, you complete one major goal but you do this by completing different smaller tasks.

Tutorials are also pieces of documentation where the reader plays along while reading. This means that the reader will have to switch back and forth between the document and the software he uses to reproduce the steps stated in the document, thereby his attention is somewhat divided. That calls for a clear structure.

• introduction
• links to already created material
• providers details and more context around information.  A writer creates a manual because s/he wants to do a very thorough job of definitively documenting a relatively complex topic of enduring value. provides best practices on the topic...not all information...just the best of the best.
  

• It's like lego, but with documentation ;-)
• A task might be: altering a config file someplace
• A tutorial would be: how to write a filesystem-based skin
• A manual would be: skinning best practices in general