Follow these guidelines to ensure your documentation is clear, comprehensible and easy to translate:

Grammar and Usage

• write with the reader in mind
• write self-descriptive topic headings that clearly identify the topic
• use short, simple sentences and words
• start with the most important idea
• be consistent in terminology and spelling: do not call the same thing by different names, and do not call more than one thing by the same name
• use active voice: for example: Use the Save command to save the file, not The Save command is used to save the file.
• use graphics and diagrams where possible
• avoid text in graphics
• avoid double-negatives
• avoid acronyms, but if you must use them, expand the acronym on its first use
• avoid idioms, colloquialisms, and slang
• write each sentence in chronological order
• avoid contractions
• have one idea per sentence
• have one topic per paragraph
• start the paragraph with a topic (introductory) sentence
• use proper grammar
• avoid starting a sentence with a conjunction
• avoid sentence fragments
• be sensitive to other cultures and countries
• avoid gender-specific language (he, she)
• avoid abstract nouns, for example, using capability to indicate you can
• consider generic placement of graphics
• write with accessibility in mind: use tooltips on graphics, font size, alternate text
• avoid deadwood words: for example: Pick a valid code should be Pick a code
• do not write as if things were people, for example, The computer remembers.
• avoid long adjective strings - use prepositions between strings
• if possible, identify which country the topic applies to

Documentation structure

• start with a summary paragraph
• avoid long text blocks
• use bullets, lists, tables and numbering where appropriate
• avoid long paragraphs and sentences
• use headings and white space
• use a glossary to define each terms