↓Skip to main content

Technical Writing

·3 mins
Writing

In preparation for a technical writing collaboration, in the past days I went through Google’s Technical Writing One course material and these are the notes I took:

The work of writing is simply this: untangling the dependencies among the parts of a topic, and presenting those parts in a logical stream that enables the reader to understand you.

  • recognise and explain terms that might be unfamiliar to the target audience
    • if there’s a good existing explanation, link to it
    • otherwise, explain yourself
  • use terms consistently even if there’s a synonym for it: the audience might otherwise think that you want to highlight some subtle differences
    • it’s fine to introduce shortened name versions, though
      • “Protocol Buffers (or protobufs for short) …”
  • write acronyms in their extended form when you introduce them for the first time
    • “Transport Layer Security (TLS) …”
  • use acronyms sparingly, only when
    • they are significantly shorter than the full term, and
    • they appear many times in the document
  • watch out for ambiguous pronouns
    • place them as close as possible to the referring noun (<5 words from it)
  • use the active voice in most of the sentences
  • prefer strong verbs over mild ones, to keep readers engaged
    • “Dividing by zero raises the exception” instead of “The exception occurs when dividing by zero”
    • “The system generates this error when …” instead of “This error message happens when …”
  • strengthen the sentence by replacing “There is/are” with “You” (when appropriate)
    • “You should know two disturbing facts …” instead of “There are two disturbing facts…”
  • improve readability and maintainability by keeping sentences (and documentation in general) short
  • write a single idea in each sentence (single-responsibility principle)
  • replace long sentences with a list
    • indentation combined with left-to-right, top-to-bottom scanning is easier on the eye
  • write a great opening sentence
    • busy readers will focus on that one, so you want to keep them engaged!
  • focus each paragraph on a single topic
  • answer what, why, and how in each paragraph
    1. What are you trying to tell your reader?
    2. Why is it important for the reader to know this?
    3. How should the reader use this knowledge? Alternatively, how should the reader know your point to be true?
  • good documentation = knowledge and skills your audience needs to do a task − your audience’s current knowledge and skills
    1. identify your audiences’ role(s) to approximate their knowledge
    2. determine what they need to learn
    3. write to meet your audience’s needs, paying attention to vocabulary and cultural neutrality; make sure your explanations are clear to novices
  • clearly define the document’s scope as well as its non-scope
  • specify the document’s intended audience
  • summarise the document’s key points at the start
  • use compare-and-contrast to enable your audience to gauge your ideas against concepts they already understand
  • write in the second person
  • read it out loud
  • set your first draft aside and come back to it after some time (1-3h), to read it with fresh eyes
  • find a peer editor
  • use illustrations
    • first, write the caption (“after viewing this graphic, what should the reader remember?”)
    • then, create the illustration that best represents it
    • use callouts and other graphic elements to focus the readers’ attention
  • provide qualitative sample code, when applicable
↑