Style, voice, and tone

Always write your documents in simple, easy-to-understand sentences. Voice and tone refer to the mood or attitude of a specific work of writing. Ensure that your voice and tone is succinct, natural, and friendly towards the reader. Avoid a tone that is commanding or too pushy. Try to keep the document contents straightforward and effortless to understand.

Don’t try to be overly colloquial. On the other hand, don’t overdo a professional tone; a formal or robotic tone is unfit as well. Try to achieve a balance between colloquial and formal language, that is suitable for providing knowledge and information. The document should persuade readers, rather than overwhelm them with verbiage.

Even if a conversational tone helps, don’t overplay the humor part. Keep the emphasis on the reader; the reader should not feel out of place. WordPress is a global project, with the majority of users being non-native English speakers. Hence, take into consideration that your document may be translated into other languages. Ultimately, educating and providing information to the reader is of the utmost priority.

Try to avoid these things

• Colloquial or idiomatic expressions.
• Unnecessary metaphors or humor.
• Cultural and regional references.
• Technical jargon or slang.
• Shortcuts, symbols, and abbreviations that could easily be spelled out.
• Being overly pretentious or conspicuous.
• Dictating or ordering procedures in a condescending tone. For example, You must click Publish or You need to click Publish.
• Being overly polite. For example, Please click Publish.
• Using exclamation points unless absolutely needed.
• Capitalizing words where it is unnecessary.
• Excess use of the same phrases and pronouns.
• Ableist language or figures of speech.
• Long, complicated, and disconnected sentences.
• Content that would insult any group or individual.
• Assumptions on the reader’s fundamental understandings.
• Using unorthodox conventions.
• Heavily biased and disparaging information.

Not complying to these guidelines may result in increased document perplexity and could impede the reader’s understanding.

Things that are encouraged

• If you are finding it difficult to achieve a suitable tone and structure, try seeking input from your counterparts.
• Proof-reading the document for the tone and structure.
• Overall simplicity of the document.
• Using transition words such as moreover, although, hence, and therefore.
• Using active voice whenever possible.
• Using contractions such as they’ve and don’t.
• Brief and concise sentences.
• Using second person by keeping emphasis on the reader such as you.
• Using conditional phrases.
• Defining technical terms, jargon, and abbreviations.
• Referring proven research and facts.

Tone for specific documentation types

User documentation

Users search through documentation for an answer to a question. Maintain a friendly, informal tone, but focus on being clear and concise in a knowledgeable manner. Get to the point promptly. Explain technical terms, but be careful not to be condescending. To ensure clarity, start by briefly specifying the context of the current topic.

Write user documentation considering that many users are not native English speakers. Avoid long narrative paragraphs; keep paragraphs short and focused, with consistent vocabulary and phrasing that is easy to understand for readers.

Examples

Developer documentation

In most cases, developers are often searching through documentation for an answer to a specific technical question. Maintain a direct and precise tone while writing developer documentation. Use the same tone you would for user documentation, but you can assume a higher level of technical knowledge in your readers. In tutorials, it’s helpful to specify what technical knowledge is being assumed.

For a code reference, be as direct as possible. A conversational tone is less appropriate here.

Examples