loading...
Cover image for Tech Writing Cheat Sheet

Tech Writing Cheat Sheet

lucis profile image Lucis ・2 min read

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!

Discussion

pic
Editor guide