Write for an audience of someone who learned English at 20, is under a pressing deadline, and has a migraine.
Don't write for your friends and colleagues who already understand your advice. Don't write for the audience of your blog. Definitely don't write for the teacher who marked generously for big words.
When writing guidance, begin with your main point. Follow up with brief reasoning, clarifications and caveats in later paragraphs.
Avoid the passive voice, and use the active voice.
You can test if something is in the passive voice by adding "by zombies" after the verb or verb phrase:
"The passive voice is to be avoided [by zombies]".
You can address your audience as "you", and word things in the imperative tense:
"If you are designing API that accepts a time measurement, express the time measurement in milliseconds."
rather than
"Time measurement values in APIs should be expressed in milliseconds [by zombies]"
Write your first draft, then cut words ruthlessly.
Cut out any unnecessary detail or opinion, and any unnecessary phrases like "it may be considered that".
If it's too long, it becomes physically painful to read, especially if it's part of an even longer document. Nobody is going to read all the way to the end of a section, unless it's very short. So, if you have important information to share with people: keep it brief!
If a sentence is longer than 15-20 words, you can probably break it into two sentences, or cut out unnecessary words. If a sentence has a colon or a semi-colon in the middle, you can usually break it there.
They can be as short as one sentence, and probably shouldn't be longer than three.
Unless a technical term of art is absolutely necessary, try to find a simpler way to express your ideas.
In many cases, this involves being more specific or direct, which also makes it easier to understand.
Compare:
Thus, for time stamps that do not need to correspond to an absolute time, consider using DOMHighResTimeStamp, which provides monotonically non-decreasing sub-millisecond timestamps that are comparable within a single browsing context or web worker.
and
So, if a date-time is only used to compare timing of events, and not to show a formatted date-time value to the user, consider using DOMHighResTimeStamp instead.
Note that you can replace "Thus" or "Therefore" with "So" in many cases as well.
Prefer common contractions to their longer forms.
Contractions are easier to read, and many are among the 100 most common words in English.
Here are some phrases you can find and replace:
| Replace | With |
|---|---|
| "do not" | "don't" |
| "it is" | "it's" or just omit |
| "is not" | "isn't" |
| "it is not" | "it isn't" or "it's not" |
| "cannot" or "can not" | "can't" |
| "are not" | "aren't" |
| "does not" | "doesn't" |
| "will not" | "won't" |
| "could not" | "couldn't" |
| "there is" | "there's" |
| "that is" | "that's" |
See also:
- Use "they", "them", "their" etc.
instead of "he", "she", "he or she" and related pronouns,
unless referring to a specific person.
- If referring to a specific person, respect whatever pronouns they use for themselves.
- If you're not used to "they" referring to a single person, the Wikipedia article has a good, succinct introduction.
- Avoid ableist metaphors, i.e. anything which uses a term referring to a person's physical or mental ability or disability as a metaphor.
- Avoid racist metaphors, including anything that might be interpreted as a reference to skin colors or allusions to racialized historical events.