December 25, 2020

Technical Writing, the Google course

Google has a public Technical Writing course.

I encountered it after meeting & interviewing the inimitable Ed Bacher, who served as a Staff Technical Writer at Google for 7 years.

I condensed the 2-part technical writing course contents into notes below:

Technical Writing One

  • Understand the parts of English speech
  • Define terms, or preferably link to an existing definition
  • Acronyms are ok, guiding principles about using them:
    • Don’t define acronyms that would only be used a few times.
    • Do define acronyms that meet both of the following criteria:
      • The acronym is significantly shorter than the full term.
      • The acronym appears many times in the document.
  • Use pronouns carefully, they’re not required and can confuse readers
  • Avoid passive voice, use active voice–this requires training to unlearn
  • Use active verbs, avoid “be/is/are/am/was/etc.”, “occurs”, “happens” (source)
    • A sentence’s verb defines its strength
  • Sentences contain a single thought, not multiple (source)
  • Lists and tables are great
    • Only include alike items in lists
    • Introduce tables with a preceding sentence
  • Paragraphs
    • One thought per sentence, one topic per paragraph
      • Answer what, why, and how
    • Opening sentences are critical…
      • so focus your energy on them
      • establish the paragraph’s point
      • rhetorical questions also work
  • Define your audience
    • “After reading the documentation, the audience will know how to do the following tasks”
    • Match vocabulary to audience
    • Curse of knowledge
    • Keep your writing culturally neutral
  • Markdown is useful

Technical Writing Two

Takeaways

These are invaluable lessons, and also apply for other forms of text-based communication (email, instant-messaging).