Tone refers to the mood or attitude of a specific piece of writing. For example, your tone in a personal email might be more informal than one you send at work. Voice reflects overarching characteristics that shouldn’t change much between documents. The voice of WordPress and its community is friendly but professional.
This guide is mainly for English-language documentation. If you are not writing in English, please also refer to the guidelines for your locale.
Voice
Be friendly: In English, use contractions (I’m, don’t) and write in the second person. Use language that is accessible to your target audience. Avoid jargon.
Be professional: While writing in a friendly, accessible manner, be sure not to overdo it. Don’t use too many exclamation marks, and don’t use slang or web shorthand. Write concisely and use the active voice whenever possible.
In general, remember that documentation is translated into many languages. It’s important to write in consistent standard English and avoid cultural references and idioms. For example, users outside the US may not know what the Super Bowl is, and expressions like “dot your I’s and cross your T’s” are difficult to translate.
Tone
User Documentation
Users search the documentation for the answer to a question. Maintain a friendly, informal tone, but focus on being clear, concise, and very precise. Get to the point as quickly as possible. Explain technical terms, but be careful not to be condescending. To ensure clarity, start by briefly specifying the context of the current topic.
Keep in mind 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 for all your readers to understand.
Examples describing a functional component of the WordPress admin:
Good example:
Bad example:
Examples describing a technical implementation:
Good example:
Bad example:
Developer Documentation
Developers are often searching the documentation for an answer to a specific technical question. Your tone here should be direct and very precise. 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.
Good example:
Bad example:
Good example:
Bad example:
