From the Ten Precepts of Taoism, this is the Fifth:
Don't utter bad words.
Don't use flowery and ornate language.
Be straightforward within and without.
Don't commit excesses of speech.
My approach to technical writing strives for a similar spirit.
Acceptable technical writing should be accurate, with a professional level of spelling, grammar, and punctuation. Excellent technical writing requires more than that.
I've collected the guidelines on this page over years of writing technical and instructional content. I consider every word I write carefully using these guidelines, striving to be:
For every word, ask "Is it needed?" Technical writing isn't like writing a school paper that imposes a minimum word count—you don't need to stuff in extra words. However, avoid sacrificing clarity on the altar of brevity. Use all the words you need to prevent ambiguity or distortion of meaning.
Watch out for the word "of" and phrases such as "in order to," "you can," and "there are." You often don't need them.
YES: To increase high availability, configure a virtual IP.
NO: Configure a virtual IP to increase high availability.
YES: Several restrictions apply to trial accounts.
NO: There are several restrictions that apply to trial accounts.
YES: Edit the cluster authentication settings.
NO: Edit the authentication settings of the cluster.
Leave marketing copy to the marketing team. Avoid superlatives and excessive claims.
Avoid cliches.
Use present tense instead of future tense, unless the future tense is necessary. Using present tense typically reduces word count.
YES: This button returns you to your dashboard.
NO: This button will return you to your dashboard.
Prefer active voice over passive.
YES: Invalid input triggers an error message.
NO: An error message is triggered by invalid input.
Be direct. Technical writing is not the place for mild, overly polite language.
YES: Provide the access token that you generated.
NO: Please provide the access token that you should have generated.
Prefer simple vocabulary. There's no need to use "obfuscate" if "hide" will do.
Use a style guide. This establishes a baseline standard for your team. If you're the only person working on docs, a style guide records that standard for future documentarians.
Many styles depend on personal preference, such as whether to use sentence case or capital case for headers. Whatever you choose, choose it consciously and apply it consistently.
Avoid randomly interchanging synonyms for technical terms.
I often see instructions like these:
Save the file to the XX directory ... Navigate to the previous folder.
In these instructions, the words "directory" and "folder" are used synonymously. Instead of randomly using one or the other, choose one and use it consistently.
By using synonyms for the same technical concept, you risk confusing users who might wonder if you intend a different meaning for each word. This is especially important if your documentation will be translated, or if you have foreign users for whom English is not their first language.
Choose either US or UK English. Don't mix and match them.
YES: Use this file as the template.
NO: This file should be used as the template.
To indicate causation, use "because" instead of "as." "Because" is less ambiguous and easier to translate.
Use descriptive link text instead of link text such as "click here" or "read more".
YES: Read our full mission statement.
NO: Read more.
Have a coherent information architecture. Are pages logically grouped and easy to find in the site navigation? Are heading tags used correctly, in sequential order? Are "On this page"-style content tables—with a fixed position—available for longer pages? Is a sitemap available?
Avoid "e.g." and "i.e." because their meanings might not be clear to users. Remember, you might have users for whom English is not their first language. Substitutions for "e.g." include "like," "for example," and "such as." Substitutions for "i.e." include "in other words" and "that is."
Position conditionals or circumstances at the beginning of a sentence so that users read them first and avoid making mistakes.
YES: To start over, delete this file.
NO: Delete this file to start over.
Avoid words like "easily" and "simply" because they can sound patronizing. If you describe some process as being "easy" or "simple"" and the user encounters a problem with that process, your language might only increase their frustration.
Explain terms, acronyms, and abbreviations that might be unfamiliar to the user the first time that you use them.
Use inclusive language. Avoid potentially ableist, biased, gendered, ageist, and violent language.
Problematic words include: master, slave, whitelist, blacklist, retard, kill, crazy, dummy, cripple, mankind.
Use diverse, inclusive examples. Not every example user needs to be named "John Smith".
Make minimal assumptions about your audience and their knowledge and skill levels.
Use positive language. Prefer language that emphasizes what CAN be done rather than what CAN'T.
YES: You can access this API on the Starter plan.
NO: You can't access this API on the Free plan.
Avoid colloquialisms. Not everyone understands them.
While documentation may not be prose or poetry, you can still write in a way that's pleasant to read.
Vary sentence lengths. Too many sentences of the same length in a row (whether long, medium, or short) becomes monotonous to read.
Keep sentences under ~30 words, and minimize the number of clauses per sentence.
Break up long paragraphs to avoid the wall-of-text effect.
If the product is cross-platform, your documentation must be too. If you're writing about a product that can be used by Android and iOS, then provide documentation for both platforms, not just one. Shortcuts, menu options, and features might vary by platform. Include them all.
Depend on feedback from reviewers and UX testers to validate documentation and its information architecture as much as possible.
Provide the command syntax. For complex syntax, also provide syntax examples.
Provide instructions on handling common errors and unexpected output.
Provide any relevant version and deprecation information.
Search engine optimization (SEO) ensures that users can find your documentation when they need it. Optimize your pages for discoverability and enable and use analytics to measure results.
Most of the guidelines collected here are not absolute rules. (Some are - always avoid hurtful language!) If trying to use active voice in a sentence makes it sound unnatural, don't. Once you understand the rules, you can break them when appropriate.
If you're working for an organization with a style guide, learn it and use it. These might include additional guidelines such as avoiding exclamation marks, avoiding first person voice, specific date and time formats, or even guidelines that conflict with mine.
For example, some companies prefer their documentation to be written with some marketing copy, or in a very casual tone. Some companies forbid exclamation marks, while others sprinkle them in liberally. Use what they use.
Pick your battles. Provide your best advice and effort, but recognize gracefully when something isn't your call to make.
Many companies and organizations publish their documentation style guides online. These are some of my favorites: