General Writing

Introductions

1. Explicit Goals

• Clearly state the purpose of the document.
• Tutorial: explain the objective and motivation.
• Informational document: educate the audience (e.g. wrt a concept or feature).

2. Implicit Goals

• Establish a relationship with the reader.
• Create trust and credibility.

Content Body

• Limit details and explanations to company contributions, which are concepts, processes and solutions. Supplementary information and prerequisites must be referenced to provide context and clarity, but the reader should be pointed to the source material via external links.
• Writing should be data-rich and dense with information. When describing something, use adjectives that are quantifiable such as maximum, or majority. Quantities should be numeric and represented by a value/range, order of magnitude, or percentage.

Grammar Rules of Note

1. "which" vs "that"

• In a defining clause, use that.  A defining clause gives information essential to the meaning of the sentence.
• In non-defining clauses, use which. Which is as disposable as a sandwich bag. If you can remove the clause without destroying the meaning of the sentence, the clause is nonessential and you can use which.

2. "a" vs "an"

• The indefinite articles 'a' and 'an' follow the sound, not the spelling.
  • an hour
  • an honorable fellow
  • an unfair world
  • a historic moment
  • a utopian idea
  • a one-track mind