Aim, in your documents, for a voice and tone that's conversational, friendly, and respectful without 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, be memorable; you can even be a little funny now and then. But remember that the primary purpose of the document is to provide information to someone who's looking for it.
Remember that many readers are not native speakers of English, and that many of them come from cultures different from yours, and that your document may be translated into other languages.
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.
- Jokes at the expense of customers, competitors, or anyone else.
- Exclamation marks, except in rare really exciting moments.
- Wackiness, zaniness, and goofiness.
- Mixing metaphors or taking a metaphor too far.
- Funny lines that aren't closely related to the topic, or that require a lot of off-topic verbiage, or that obscure information.
- Phrasing that denigrates or insults any group of people.
- Phrasing in terms of "let's" do something.
- Using phrases like "simply" or "It's that simple" or "It's easy" in a procedure, unless it's an extraordinarily simple/easy 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.
Not recommended: To view the document, please click View.
Recommended: To view the document, click View.
Not recommended: For more information, please see [link to other document].
Recommended: For more information, see [link to other document].
|Too informal||Just about right||Too formal|
|Dude! This API is totally awesome!||This API lets you collect data about what your users like.||The API documented by this page may enable the acquisition of information pertaining to user preferences.|
|Just like a certain pop star, this call gets your "Telephone" number. The easy way to ask for someone's digits!||To get the user's phone number, call
||The telephone number can be retrieved by the developer via the simple
expedient of using the
|Then—BOOM—just garbage-collect (or collecter des garbáge, as they say in French), and you're golden.||To clean up, call the
||Please note that completion of the task requires the following prerequisite: executing an automated memory management function.|