Tech Writing Cheat Sheet

This is a curated list of summaries from Google's Tech Writing courses that I constantly consult when reviewing documents since I sometimes forget things.

General/Introduction

• Determine your audience and what they will learn.
• Fit documentation to your audience.
• Introduce a document's scope and any prerequisites.
• Outline a document. Alternatively, write free form and then organize.
• Make a practice of continuous revision.
• Establish your document's key points at the start of the document.
• Read documents out loud (to yourself) when reviewing.
• Find a good peer editor.
• Return to documents well after you've written the draft.
• Compare and contrast with something that readers are already familiar with.

Content

• Prefer task-based headings.
• Use terms consistently.
  • If you change the name of a variable midway through a method, your code won’t compile. Similarly, if you rename a term in the middle of a document, your ideas won’t compile (in your users’ heads).
• Avoid ambiguous pronouns.
• Prefer active voice to passive voice.
  • "Python interprets code" instead of "Code is interpreted by Python".
• Pick specific verbs over vague ones.
• Focus each sentence on a single idea.
• Convert some long sentences to lists.
• Eliminate unneeded words.
  • Like simply or just.
• Use a numbered list when ordering is important and a bulleted list when ordering is irrelevant.
• Keep list items parallel.
  • All items in a parallel list look like they "belong" together.
• Start numbered list items with imperative words.
  • "Install that".
• Introduce lists and tables appropriately.
• Create great opening sentences that establish a paragraph's central point.
• Focus each paragraph on a single topic.

Code Examples

• In tutorials, reinforce concepts with examples.
• Create concise sample code that is easy to understand.
• Avoid writing comments about obvious code.
• Keep code comments short, but prefer clarity over brevity.
• Provide not only examples but also anti-examples.
• Provide code samples that demonstrate a range of complexity.
  • Simple and complex examples.

Drawings

• Consider writing the caption before creating the illustration.
• Focus the reader's attention on the relevant part of a picture or diagram by describing the takeaway in the caption or by adding a visual cue to the picture.

If you would like to learn more about these points, check out the courses. There are two and they're very good!