Document Types

The Plone Documentation Area (aka: Plone Help Center) is made up of several different content types:

• FAQs
• How-tos
• Tutorials
• Manuals
• Error References
• Links
• Glossary Entries
  

All of these content types have a standard structure that the Documentation Team would like authors to follow.

Big Documents - The Basics

The plone.org documentation section has three big types of documentation. While these are not necessarily the kind of documents that are published more often, they are used frequently. We highly recommend that each how to, tutorial, and manual start out with the same basic information.

• Title -  Pretty much self explanatory, 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 reader's point of view to check if it makes sense. It should be as distinct and short as possible, while still being descriptive, and contain words that a reader would look for when searching documentation on a given subject.
• Purpose-  Begin each document 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- There are two kinds of prerequisites: technical and skill/knowledge - List all technology requirements as well as skills requirements. Link to anything that helps a reader fulfill those prerequisites. This should be the first paragraph after the title and purpose, so the user does not have to skip back and forth while s/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 the environment. Feel free to link to documents that teach prerequisite skills in this section.
  
• Audience- define the intended audience. Who is this document for? The End User? The Developer? Tell the reader exactly who the document is geared towards. For audience definitions, follow this link.
  
• Links- Include any links that may be helpful to completing this task. You can also put these right in with the prerequisites section if it makes sense to do so. These can be links to outside sources or anything else the author deems applicable to the content at hand.
  
• Version info- If the document applies only to certain versions of Plone (or a Product), please indicate them here.
• Tags- Select the appropriate keywords for the document.
  

How-tos

A How-to is a short document that tells you how to do one thing and one thing only. A how-to is at its simplest, a task.

Follow these hints for a successful how-to:

• Steps- each step in a task 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, and what kind of response the action will cause. Draw attention to the result text by setting it in italics.
  
• Example- if you would like to include an example to illustrate the step you just wrote, do so on the next line after the step. Draw attention to the example text by setting it in bold text.
  
• 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 multi-section 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 s/he uses to reproduce the steps stated in the document, thereby his or her attention is somewhat divided.

Follow the basic guidelines for how-tos and split up the sections of your tutorial in a logical manner. The key to a good tutorial is to make sure that it flows correctly and naturally. Use headings to break up the page of a tutorial so that it's not one long page of solid text. Add visuals such as screen shots.

Manuals

A reference manual provides 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. A reference manual provides best practices on the topic. It does not try to contain every single detail on the topic... just the best of the best.

Smaller Documents

The plone.org documentation center has several, smaller document types that are more widely used. FAQs, Help Links, Error Reference, and Glossary Definitions are all similar in format.

Frequently Asked Question (FAQ)

An FAQ is a short question with a 1-2 paragraph answer. You can add several questions to a FAQ area and group the questions into sections.

Help Link

A help link is a link (either external or internal). It is different from a standard Plone link in that it can have section and version information. Typical Help Links:

• The Zope Book at zope.org
• CSS reference manual at W3C

Error Reference

An error reference is meant to be the explanation of a particular error, with details on how to fix it, if relevant. Typical Error References

• Expected sequence, got integer
• FS Page Template has errors: Compilation failed

Glossary Definition

A glossary definition describes a particular term used as concisely as possible. Typical Glossary Definitions:

• CMF: The Content Management Framework
• Workflow: A state machine structure used to model business processes