Documentation Style Guide

Introduction

Welcome to Openbravo documentation style guide.

This style-guide contains basic rules, tips, and suggestions for people intending to develop documentation for the Openbravo project. When different documents use the same guidelines, they are more user friendly, consistant and more simple to combine and reuse. As such, we strongly encourage all contributors to follow these guidelines for the benefit of the community.

This guide does not attempt to cover all aspects of technical writing. The objective is to be concise and focused for Openbravo documentation writers.

Writing Rules

These are some basic rules that make documents more clear, precise, and easy to understand.

Keep it simple

Use short sentences and punctuation to keep ideas clear and simple. Introduce a single idea, concept or action per sentence.

Wrong

The manufacturing module allows users to define the process plans, work requirements and work efforts; this is how the processes that produce intermediate and final goods work.

Correct

The manufacturing module allows users to define the process plans, work requirements and work efforts. This section describes how processes that produce intermediate and final goods function.

Tenses

Always use the present tense. Avoid past or future tenses if possible.

In addition, try to refrain from using must, have to, need to, will, should and similar forms.

Keep in mind that a manual describes mandatory procedures to follow to accomplish a certain task.

Wrong

You will have to press return to reboot the system.

Correct

Press return to reboot the system.

Aggressive Language

Avoid using aggressive descriptions.

Wrong

Hit return to reboot the system.

Correct

Press return to reboot the system.

Use the active voice

Using the active voice makes sentences more vigorous and strong.

Wrong

The alarm was fired by the system.

Correct

The system fired the alarm.

Use third person

Always use the third person. You should not use the personal pronouns I, you or we.

Wrong

You should run the installation script

Correct

Run the installation script

No personal opinions

A manual or any other technical document is not the right place to make statements about what you think about competitors, products or the features described.

Wrong

Select the Report option to generate a full report of the customer data. Most of the time is better to export the data and generate a report from third-party applications due to the lack of configuration settings.

Correct

Select the Report option to generate a full report of the customer data. It is also possible to export data and generate a report from third-party applications.

Avoid gender discrimination

Readers of software documentation are men and women. Unfortunately in English there no personal or possessive pronoun that denote gender neutrality. Avoid using expressions that refer to specific gender forms. Pay special attention to the she, he, him or her pronouns.

Wrong

Every user has his home directory.

Right

Every user has a home directory.

Only describe current functionalities

Avoid talking about future features or plans for a product or an application.

Wrong

Graphics may be saved as a GIF image. Support for new formats will be added in future versions.

Correct

Graphics may be saved as a GIF image.

Style and conventions

Because we use different documentation sources, including Mediawiki, a limited number of formatting styles are used:

• Bold. Use it to highlight the importance of a word or a concept in a sentence.

• Italic. Use it when quoting a piece of a text from another source, a piece of text in another language or naming an application option.

There are also some conventions to consider:

• When describing options always start from left to right and from top to bottom.

• Use a concatenated list of options to describe how to reach a specific option. For example, use File > Open to open an existing file.

• Do not use contractions (don't, you're, etc).

Writing for a global audience

Open source software is global by definition. Keep in mind that people from all over the globe have access to it and its related documentation.

Some important recommendations:

• Avoid using names of people, addresses, and other sample information that are not common in the English language.

• Remember that currencies and formats to represent dates and numbers are not the same in every part of the world.

Final checklist

Upon completing a document, it is a good idea to perform the following quick checklist:

• It is clear? Does the text follow well from paragraph to paragraph?
• It is concise? Does it have a clear communication style?
• It is coherent? Does the text jumps from topic to topic?
• It is grammatically correct? Have you spell checked the text? Have you asked a native speaker to proof-read your text?

Links

Interesting links and references related to documentation.

• Openbravo documentation SourceForge forum
• Fedora Project Documentation Guide
• Ubuntu Documentation Style Guide