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:
- 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
- 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
- Self-editing (source)
- 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
These are invaluable lessons, and also apply for other forms of text-based communication (email, instant-messaging).