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)
  • Can you remove words? Do it
  • “That” and “which” are different special, avoid them
• 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

• Self-editing (source)
  • Consider establishing a style guide
  • Know your audience, and think like your audience
  • Read it out loud
  • Come back to it later
  • Re-approach your writing in a different medium
  • Find a peer editor
• Organizing large docs
  • E.g. tutorials or conceptual guides
  • Create an outline
    • A clear outline allows 3rd party contributors
    • Provide navigation, table-of-contents
• Illustrating with images
  • Write caption first, then create/acquire illustration
  • Avoid illustrations that are too complex
  • Focus the reader by circling/arrowing the point of interest
  • Revise illustrations the same as text (“re-illustrating”)
• Creating sample code
  • A lot of self-evident advice

Takeaways

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