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.
Good 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, don't sacrifice 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 postpone a delivery, call 1-800-123-4567.
NO: In order to postpone a delivery, you can call us at 1-800-123-4567.
YES: Several restrictions apply to trial accounts.
NO: There are several restrictions that apply to trial accounts.
YES: This lets you change the background color.
NO: This lets you change the color of the background.
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.
Prefer simple vocabulary. There's no need to use "obfuscate" if "hide" will do.
The meta-guideline: 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 that 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.
Pick either US or UK English. Don't mix and match them.
For clarity, use a forward slash when referring to a folder vs a file.
To indicate causation, use "because" instead of "as." "Because" is less ambiguous and easier to translate.
Use descriptive link text. Don't use "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.
Avoid colloquialisms. Not everyone understands them.
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.
Break up long paragraphs. 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.
Have someone other than the original writer step through any step-by-step instructions and review them. The reviewer should not just read the steps, but actually attempt to follow them.
Provide example inputs and outputs.
Provide instructions on handling common errors and unexpected output.
Most of the guidelines collected here are not absolute rules. (Some are - please 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: