Tone of Voice and Audience

The voice and tone of a writing can greatly impact how the reader perceives the content.

Too formal and you might scare the reader away. Too friendly and you might degrade the value of your writing. In general, strive to advocate for the user and help them understand how the product functions, how the features coexist, and how the functionality integrates within each context.

Basic Things to Do

Present the information from a user perspective. Users need to understand what they can do with a functionality, so avoid just listing and advertising the features, but provide them with context.
Try to sound like a knowledgeable friend who understands what the developer wants to do. The primary purpose of the documentation is to provide information to someone who is looking for it.
Try to deliver such a style, tone, and voice of the technical documentation that is respectful and natural.
Try to use such a style, tone, and voice of the technical documentation that is not colloquial or frivolous, pushy or pedantic, or super-entertaining or super-dry.

Basic Things to Avoid

Phrasing that belittles or insults any group of people.
Unnecessary gendering of language. Use "they", "their", "theirs" instead of "he", "him", "his" or "she", "her", "hers".
Phrases such as "simply" or "it's that simple" or "it's easy" in a procedure.
Phrasing in terms of "let's" do something. Exception are acceptable for getting started step-by-step guides.
Placeholder phrases like "please note" and "at this time".
Jokes at the expense of customers, competitors, or anyone else.
Absurdity, silliness, and funny lines.
Culture-specific language.
Choppy or long-winded sentences.
Buzzwords or technical jargon.
Exclamation marks.
Being too cutesy.
Current pop-culture references.
Abbreviations.
Metaphors.

Writing for Global Audiences

The Progress official product documentation serves global audiences. Aiming at different cultures requires simple, objective, and non-ambiguous language, which translates well and does not provide room for interpretation.

For more information and examples, refer to the article on choosing the appropriate language.

Using Simple Language

Use common en-US vocabulary. Avoid foreign words or words of foreign origin including Latin abbreviations such as "e.g.," and "i.e.,". Use their human-readable equivalents such as "for example," and "that is," respectively.
Use simple, short, and non-ambiguous words and phrases.
Use correct and consistent terminology. Avoid creating new terms.
Use very specific words and phrases and avoid generalization.
Use objective language:
- Do not use qualifications such as "good", "best", "worst", and so on.
- Do not use slang, jargon, humor, sarcasm, colloquialisms, idioms, emoticons, and metaphors.
Avoid using the same word for different parts of speech.
Avoid culture-specific references that might not be widely understood, such as holidays and celebrations, monetary units, and phone number and address formats.
Avoid using symbols instead of words in running text even if you are space-constrained.

For more information and examples, refer to the article on using simple and unambiguous language.

Using Short Sentences and Paragraphs

Short paragraphs improve the readability of the document as they add whitespace to it and help communicate the logical flow of the content.

Keep sentences and paragraphs short and concise.
If a sentence or a paragraph is becoming too long, split it.
As a rule of thumb:
- Use up to 25 words in a sentence.
- Use between two and four sentences in a paragraph.
- Keep a paragraph up to six lines long.

Not that good	Much better
The PanelBar displays hierarchical data as a multi-level, expandable component and is stateless, which means that to store its state and configuration options, you must use a high-order component.	The PanelBar displays hierarchical data as a multi-level, expandable component. To store its state and configuration options, use a high-order component.