Clear sentences

Comedy writers seek the funniest results, horror writers strive for the scariest, and technical writers aim for the clearest. In technical writing, clarity takes precedence over all other rules. This unit suggests a few ways to make your sentences beautifully clear.

1. Choose strong verbs

  • Use: Precise, strong and specific verbs.
  • Reduce:
  • forms of be: is, are, am, was, were, etc.
  • occur
  • happen

Weak and Strong:

  • Weak: The error occurs when clicking the Submit button.
  • Strong: Clicking the Submit button triggers the error.
  • Weak: This error message happens when...
  • Strong: The system generates this error message when...
  • Weak: We are very careful to ensure...
  • Strong: We carefully ensure...

Exercise

Bad: When a variable declaration doesn't have a datatype, a compiler error happens. - Good: When a variable declaration doesn't specify a datatype, the compiler generates an error message. - Good: If you declare a variable but don't specify a datatype, the compiler generates an error message.

Bad: Compiler errors occur when you leave off a semicolon at the end of a statement. - Good: Compilers issues errors when you omit a semicolon at the end of a statement. - Good: A missing semicolon at the end of a statement triggers compiler errors.

2.Reduce there is/there are

  • Most cases - simply remove there is / there are
  • Removing there is replaces generic subject with better subject.
  • Bad: There is a variable called met_trick that stores the current accuracy.
  • Good: A variable named met_trick stores the current accuracy.
  • Good: The met_trick variable stores the current accuracy.

3. Minimize certain adjectives and adverbs

  • Adjectives and adverbs amazing in fiction / poetry.
  • But loosely defined and subjective for technical readers.
  • Worst: Technical documentation may look like marketing material.
  • E.g. (Good adds accuracy and belivability:
    • Bad: Setting this flag makes the application run screamingly fast.
    • Good: Setting this flag makes the application run 225-250% faster.