Академический Документы
Профессиональный Документы
Культура Документы
Use US English
Throughout Openbravo, US English is the standard for all written materials.
General Rules
-our vs. -or
UK words ending in -our (such as flavour) lose their U when converted to US English. For example flavour
becomes flavor, colour becomes color. The same thing usually applies to words with -our in the middle, so
behaviour becomes behavior.
Double Consonants
When you convert a verb to its -ing form, remember that US English has a single, not a double consonant.
For example travelling becomes traveling, levelling becomes leveling etc.
US English
Analyse
Analyze
Behaviour
Behavior
Cancelling / Cancelled
Canceling / Canceled
Centre
Center
Cheque
Check
Colour
Color
Customisation
Customization
Customise
Customize
Favourite
Favorite
Labour
Labor
Licence
License
Travelling
Traveling
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.
Punctuation
Exclamation marks
There are virtually no circumstances where it is acceptable or necessary to use an exclamation mark in
documentation or in error messages.
Abbreviations
Do not use an apostrophe for plural abbreviations: Wrong: Use the Purchase Order window to create PO's
Right: Use the Purchase Order window to create POs
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.
Also, be careful about expressing an opinion on whether a task is easy or not. If the user makes a mistake
when you have mentioned that a task is simple, it can make them feel stupid even if the mistake is not their
fault. For example, avoid expressions like:
"It is easy to configure the application using the Wizard".
Capitalization
Avoid over-capitalization. It can be tempting to capitalize particular words in a sentence just because they
seem important, but this looks untidy and makes it hard to maintain consistency in a long document. Only
proper names, menu items and proprietary names require leading capitals.
Terminology
Checkbox
Checkbox is all one word (not check box). Checkboxes are either selected or cleared.
For example:
"Select the Active checkbox to make the field visible" "Clear the Active checkbox to make the field
invisible".
Login vs Log in
The verb is Log in and Log into "Log in using the password provided" "Log into Openbravo ERP" The noun
or adjective is Login "You will need valid Login credentials to use the system"
Dudas / doubts
"Doubt" in english usually has quite a negative meaning. A better translation is questions or queries.
Wrong: If you have any doubts about Openbravo, consult the wiki.
Better: If you have any questions about Openbravo, consult the wiki.
His / hers
In English, only people have a gender. Things are always neutral and take the possessive pronoun "its"
(without an apostrophe).
"Directory/subdirectory/file.extension" format.
Orient the user by starting with the first thing the user needs to look for. For example:
From the File menu, select Document > New > Template.
not
Select Document > New > Template from the File menu.
Platform
Openbravo runs on many different platforms. When documenting a feature that varies by platform, note the
platform before the example or exception. Readers can then skip sections, rather than reading a paragraph
before finding it is not relevant, and having to search for the correct section.
Phrase language and layout in a way that allows future editors familiar with a platform to add valid
examples. Platform variations are a sensitive topic, keep language neutral and factual. For example:
Wrong
To start Openbravo POS double click start.bat
Correct
Linux
To start Openbravo POS run the shell script start.sh either by clicking it or by typing ./start.sh from a shell.
Windows
To start Openbravo POS run the batch file start.bat either by double clicking it or by typing start.bat from
the command line.
Other Conventions
Final checklist
Upon completing a document, it is a good idea to perform the following quick checklist:
Links
Interesting links and references related to documentation.