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.

See also