Creating Documentation for Plone.org

Best practices and tips for writing good documentation for plone.org

Introduction

A word on writing for plone.org

So you want to write documentation for Plone.org? Well you're in the right place! This tutorial is meant to be a starting point for those who want to write any kind of documentation for plone.org. The information contained in this tutorial has been developed by the plone.org Documentation Team in an effort to help all contributors produce great documentation without (much) pain. Consider this your crash course in technical writing.

The following pages contain many best practices for creating documentation. We strongly encourage you to apply these to your documentation efforts. We've filtered out the best of the best to help you create wonderful documents that will in turn help users hone their skills.

What’s appropriate documentation?

Identify the true goal of your documentation: is it marketing, or is it truly useful for the end user?

In order to guard against showing favoritism for third party products, editors for the documentation system need to consciously consider whether the goal of a given document is to provide useful information to an end user in the form of a how-to or tutorial, or if it is more of a marketing-type document.

These decisions should be made on a document-by-document basis, and our guiding concern should be whether or not the document will be found by the people who need it. (Content that tends to being advertising for a commercial product, rather than documentation, should always be declined.) The position of the Plone Foundation has always been that commercial add-on products for Plone that respect the GPL (eg, Enfold products) are perfectly permissible to be listed on plone.org/products and there is no reason that they can't also be documented on plone.org.

The big difference between documentation in a product's own section and docs in the documentation section is their inclusion in the topical listings. Both are searchable from the Documentation search.

Some documentation clearly belongs in the product's own documentation section. For example, the PloneFormGen how-tos, which clearly cover PFG issues. Folks who need these will be searching with the term “PloneFormGen,” and will find what they need.

On the other hand, there are documents that we will want folks to find when they're searching topically. For example, we want someone searching the Windows installation topic section to find a document on "Using Plone with IIS" that focuses on Enfold Proxy to find it. Part of the consideration here is strategic. We do not have multiple, equally good, mechanisms for installing with IIS. We really want people to find that doc in the installation section.

The same thing is true of the new doc on handling multiple docs via Enfold Desktop. We do not have any other comparable products. We really want folks who use Windows front ends in an Intranet setting to find this document when they're browing topically.

If in doubt, the question of whether a document belongs should be posed to the plone-docs community for a decision.

Document Types

What kind of document do you want to create?

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.

The overall structure of a document can greatly improve a piece of documentation. If the reader feels like s/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.

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

Writing

Some helpful tips on writing documentation

Using consistent writing styles and textual elements will help standardize your document and make them easier to use for the reader. This is by no means a comprehensive list of style and text usage. If you are curious and want to learn more, look into The Chicago Manual of Style.

Writing Style

Tone, voice, tense, grammar, and choice of words (among other things) all make up part of a writer's style. Every writer's style is influenced most heavily by his or her personality. You may have noticed though that technical documents tend to have a very dry style to them. The goal for technical documentation is to convey information in a clear and concise way. By using the following style techniques, you can help make sure your document is understood.

Present Tense

Use the present tense of the verb in all sentences. Using the present tense shows the user clearly that this is the action s/he should take now (instead of in the future). Switching back and forth between tenses confuses the reader. Using present tense consistently helps the reader follow along the document and perform the steps in the order they are supposed to occur.

Action Words

Action words are verbs that describe what action the user should take. You may also know this as using the active voice when you write. An action word is simply something you do. We use action words when we want to direct the reader to do something. Below is a list of example action words that are commonly used to describe navigation. ^*

Term	Use
Arrow Keys	Use to collectively refer to the left, right, up or down arrow keys on the keyboard.
Browse	Use browse through a list (database, document, and so on) not browse a list.
Click	Use click rather than choose or select, to refer to a user choosing or selecting a command or option. Do not use click on or click at; however, click in the window is acceptable. Click the button is also acceptable.
Close	Use close for windows, documents, and dialog boxes. For programs or network connections, use end or quit.
Deselect	Do not use. Instead, use cancel the selection or clear.
Dialog box	Always use dialog box and not just dialog or pop-up window.
Highlight	Do not use. Instead, use select. Refer to the selected material as the selection.
Icon	Use to describe a graphic representation of an object that a user can select and open.
Install	Use install when referring to hardware such as device drivers. Use set up when referring to software or components.
Key combinations	Use a plus sign to indicate key combinations such as shortcut keys and access keys.
Press	Use when pressing a key initiates an action within the program or moves the user's position.
Enter	Do not use enter as a synonym for type, except to indicate that a user can either type or click a selection, such as from a list in a box.
Type	Use type, not enter, to direct a user to type information that will appear on the screen.
Use	Use in situations when press might be confusing, such as when referring to a type of key such as the arrow keys or function keys.

*Please note that this list is by no means the end all be all of words to use to describe navigation. They are simply examples of common usage in technical documents.

English Grammar

Learning proper grammar is not what anyone would really consider a fun or easy task. The English language is notorious for its complicated and sometimes even contradicting grammar rules. Use the best grammar that you know and if you are unsure, consult a grammar book like The Gregg Reference Manual or The Elements of Style. Once you have a draft of your document finalized, also feel free to email the documentation team mailing list and ask someone to review specifically for grammar details.

Textual Elements

When we talk about textual elements, we're talking about format, punctuation, and white space. (yes, white space)

Since plone.org uses kupu as its editor, we suggest that you use all the provided styles in the drop down menu. This will make sure all your headings, etc. are all consistent.

Below are some other helpful hints on how to use text and white space to make your document more usable.

Headings- Use pre-defined headings in kupu as appropriate.
Text Justification- Text should normally be left justified with a ragged right edge.
White Space- Use white space to separate information so that readers can easily identify section and to provide a frame for graphics.
Abbreviations- Use abbreviations sparingly. Spell out the acronym or abbreviation with first time it is used in the text and follow in parenthesis with the abbreviation.
Bulleted list- Use the standard formatting in kupu. Start each list with a stem sentence that introduces the list in some way; use a colon at the end of the stem sentence.
Numbers- Use the standard number function in kupu. Remember to number each step (action) in your document!
Links- Use the standard formatting from kupu.

Attention Getters

Use these to help draw attention to certain things the reader should pay careful attention to.

Item	Description	Format
Result	Use to indicate a response that the user should see.	Result:
Example	Use to highlight an example to further illustrate a step.	Example:
Note	Use for content for which users should take special note.	Note:
Tip	Use for content that user may find helpful or nice to know, such as a shortcut or best practice.	Use the Call-out format from drop down
Caution	Use for content that users should know to avoid minor frustration or inconvenience (like losing data).	Use the Pull-quote format from drop down
Warning	Use for content that users should know to avoid serious, irreversible damage, or loss of data.	Use the Pull-quote format from drop down

How to Submit a Document for Review

Here are the steps needed to create a document to be included in the core plone.org docs section.

Log into the www.plone.org site.

Follow the appropriate link:

http://plone.org/documentation/tutorial
http://plone.org/documentation/how-to
http://plone.org/documentation/faq

You can add other types like a FAQ by first opening an existing FAQ, then using the breadcrumbs to navigate one level up. When adding a tutorial or a how-to, keep in mind that how-tos are quick guides to how to accomplish a task, whereas a tutorial is generally something that walks a user through a multitude of steps and is, in essence, a long how-to.

Once you're in the right spot, you'll see the 'Add' button appear on the toolbar.