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.
- 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.
- 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.
- 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.
- 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.
- 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!