Voice and tone

In your documents, aim for a voice and tone that's conversational, friendly, and respectful without using slang or being overly colloquial or frivolous; a voice that's casual and natural and approachable, not pedantic or pushy. Try to sound like a knowledgeable friend who understands what the developer wants to do.

Don't try to write exactly the way you speak; you probably speak more colloquially and verbosely than you should write, at least for developer documentation. But aim for a conversational tone rather than a formal one.

Don't try to be super-entertaining, but also don't aim for super-dry. Be human, let your personality show, and be memorable. But remember that the primary purpose of the document is to provide information to someone who's looking for it and may be in a hurry.

Consider that readers come from many different cultures and may have varying levels of ability reading English. As much as possible, avoid culturally specific references. Simple and consistent writing can also make it easier to translate documents into other languages. For more information, see Writing for a global audience.

For other writing best practices, see the following resources:

• Write accessible documentation
• Write inclusive documentation

Some things to avoid where possible

• Buzzwords or technical jargon.
• Being too cutesy.
• Ableist language or figures of speech.
• Placeholder phrases like please note and at this time.
• Choppy or long-winded sentences.
• Starting all sentences with the same phrase (such as You can or To do).
• Current pop-culture references.
• Exclamation marks, except in rare really exciting moments.
• Wackiness, zaniness, and goofiness.
• Mixing metaphors or taking a metaphor too far.
• Phrasing that denigrates or insults any group of people.
• Phrasing in terms of let's do something.
• Using phrases like simply, It's that simple, It's easy, or quickly in a procedure.
• Internet slang, or other internet abbreviations such as tl;dr or ymmv.

Some techniques and approaches to consider

• If you're having trouble expressing something, step back and ask yourself, "What am I trying to say?" Often, the answer you give yourself reveals what you should be saying in the document.
• If you're uncertain about your phrasing or tone, ask a colleague to take a look.
• Try reading parts of your document out loud, or at least mouthing the words. Does it sound natural? Not every sentence has to sound natural when spoken; these are written documents. But if you come across a sentence that's awkward or confusing when spoken, consider whether you can make it more conversational.
• Use transitions between sentences. Phrases like Though or This way can make paragraphs less stilted. (Then again, sometimes transitions like However or Nonetheless can make paragraphs more stilted.)
• Even if you're having trouble hitting the right tone, make sure you're communicating useful information in a clear and direct way; that's the most important part.

Politeness and use of please

It's great to be polite, but using please in a set of instructions is overdoing the politeness.

Recommended: To view the document, click View.

Not recommended: To view the document, please click View.

Recommended: For more information, see [link to other document].

Not recommended: For more information, please see [link to other document].

Examples