Style
Some language structures, tenses etc. makes docs unclear. This page is about what kind of language to use.
General advices
-
Avoid passive voice and clearly state who is the subject. It's also hard to translate passive voice to some languages.
-
Use the noun (referent) instead of "it" when "it" is undefined or can be unclear.
-
Use specific terms instead of vague and generic ones.
-
Name your ideas.
-
Be terse. Translation costs are huge (0.25$ / word / language)
-
Make your sentences simple.
-
Use simple words. You can prepare a list of common simple English words and configure your text editor to underline all words that are not in the list.
-
Use hemingwayapp.com.
-
Follow RFC language guide.
-
Read good example:
- Vintage cookbooks
- Martha Stewart
- Dorothy Parker
Simplified Technical English
Use Simplified Technical English which is a carefully limited and standardized subset of English to reduce ambiguity.
-
Write shorter sentences.
-
One topic per sentence (especially important for smart people because it's harder for smart people to follow this rule).
-
Use valid nomenclature. No slang!
-
There are four basic sentence structures:
- Statement, description or explanation.
-
Step and action (procedures)
"put switch in out" => "move the switch to the off position"
-
Cause and effect (fault isolation)
"test the voltage after the circuit energizes" => "energize the circuit , then make a test of the voltage"
-
Call-outs, tables and headlines (illustrations).
-
Avoid gerunds (-ing).
-
Avoid nouns as verbs (i.e. "test" => "make a test").
-
Avoid conditional tenses.
-
Use "can" to indicate a possibility.
-
Avoid word clusters.