14 Sep 2020 | 9 min read | 112 views

Notes: Technical Writing

Notes about Technical Writing, most content and examples are from Google’s Technical Writing course.

Words

Define new or existing terms

If the term is new, introduce it. If the term already exists, link to a good explanation. If the document is introducing too many terms, consider using a glossary.

Use terms consistently

When naming things, apply the same word or term consistently throughout your document.

🚫 Protocol Buffers provide their own definition language. […] And that’s why protobufs have won so many county fairs.

✅ Protocol Buffers (or protobufs for short) provide their own definition language. […] And that’s why protobufs have won so many county fairs.

Acronyms

When using an acronym for the first time, always spell out the full term followed by the acronym in parenthesis. You can then use the acronym going forward.

This document is for engineers who are new to the Telekinetic Tactile Network (TTN) or need to understand how to order TTN replacement parts through finger motions

Choose only one. Do not cycle back-and-forth between the acronym and the expanded version.

When to use acronyms

You should use acronyms if:

  • The acronym is significantly shorter than the expanded term.
  • The acronym/term will be referenced many times in the document.

Popular acronyms

After being used so much, acronyms develop their own identity. It’s OK to use popular acronyms such as HTML or CSS without the expanding the full term for the first time.

Disambiguate pronouns

Pronouns point to a previously introduced noun, which can sometimes cause ambiguity. In the examples below, can you tell what It and their refer to?

đźš« Python is interpreted, while C++ is compiled. It has an almost cult-like following.

đźš« Be careful when using Frambus or Carambola with HoobyScooby or BoiseFram because a bug in their core may cause accidental mass unfriending.

Some guidelines to use pronouns are:

  • Only use a pronoun after you introduced the noun.
  • Place the pronoun as close as possible to the noun.
  • If you introduce a second noun between your noun and its pronoun, reuse your noun instead of using a pronoun.

Active voice

Most sentences in technical writing should be in active voice.

Active voice vs. Passive voice

In an active voice sentence, an actor acts on a target: actor + verb + target

A passive voice sentence reverses the formula: target + verb + actor

Active Voice Example

The cat sat on the mat.

  • actor: The cat
  • verb: sat
  • target: the mat

Passive Voice Example

The mat was sat on by the cat.

  • target: The mat
  • passive verb: was sat
  • actor: the cat

Passive verbs typically have the following formula:

passive verb = form of be + past participle verb

Examples:

  • was interpreted
  • is generated
  • was formed
  • is frozen

Why use Active voice

Use active voice most of the time and passive voice sparingly. Active voice is better because:

  • Readers mentally convert passive voice to active anyway, so better use Active voice straight up
  • Passive voice reports an action indirectly and obfuscates the main idea
  • Active voice is shorter than passive voice

Clear sentences

Choose strong verbs

Choose precise, strong and specific verbs to engage readers. Imprecise, weak and generic verbs should be avoided. Examples:

Weak verbs: occur, happen, is, are (forms of be)

Weak Verbs x Strong Verbs:

đźš« The error occurs when clicking the Submit button.
âś… Clicking the Submit button triggers the error.

🚫 This error message happens when…
✅ The system generates this error message when…

🚫 We are very careful to ensure…
✅ We carefully ensure…

Reduce there is/there are

There is and There are weakens the sentence and usually associate a generic noun to a generic verb. Sometimes you can just delete the There is or There are to make the sentence more clear:

đźš« There is a variable called met_trick that stores the current accuracy.
âś… A variable named met_trick stores the current accuracy.
đź’Ż The met_trick variable stores the current accuracy.

You can sometimes repair a There is or There are sentence by moving the true subject and true verb from the end of the sentence to the beginning:

đźš« There are two disturbing facts about Perl you should know.
âś… You should know two disturbing facts about Perl.

And if no subject exists, consider creating one:

đźš« There is no guarantee that the updates will be received in sequential order.
âś… Clients might not receive the updates in sequential order.

Short sentences

Each sentence should focus on a single idea. Breaking a long sentence into a succession of single-idea sentences makes it clearer. Example:

đźš« The late 1950s was a key era for programming languages because IBM introduced Fortran in 1957 and John McCarthy introduced Lisp the following year, which gave programmers both an iterative way of solving problems and a recursive way.
âś… The late 1950s was a key era for programming languages. IBM introduced Fortran in 1957. John McCarthy invented Lisp the following year. Consequently, by the late 1950s, programmers could solve problems iteratively or recursively.

Convert some long sentences to lists

When you see the conjunction or in a long sentence, consider refactoring that sentence into a bulleted list. For example:

To alter the usual flow of a loop, you may use either a break statement (which hops you out of the current loop) or a continue statement (which skips past the remainder of the current iteration of the current loop).

Can be converted to:

To alter the usual flow of a loop, call one of the following statements:

  • break, which hops you out of the current loop.
  • continue, which skips past the remainder of the current iteration of the current loop.

Eliminate or reduce extraneous words

Remove words that only consume space and have no added value to the sentence:

đźš« An input value greater than 100 causes the triggering of logging.
âś… An input value greater than 100 triggers logging.

đźš« This design document provides a detailed description of Project Frambus.
âś… This design document details Project Frambus.

A few more common bloated phrases:

  • at this point in time —> now
  • determine the location of —> find
  • is able to —> can

Lists and tables

Bulleted list vs. numbered list

If you rearrange the items on the list and the meaning don’t change, you should use a bulleted list. If the meaning changes, the list should be numbered.

Embedded list

A list where items are all stuffed within a sentence. For example:

The llamacatcher API enables callers to create and query llamas, analyze alpacas, delete vicugnas, and track dromedaries.

When you can, try to convert embedded lists to bulleted or numbered lists.

Keep list items parallel

In parallel lists, all items look like they “belong” together and match a pattern. The first item in a parallel list establishes a pattern that readers expect to see repeated in subsequent items.

On the example below, all items are plural nouns (grammar), edible (logical category), lower case (capitalization), and without periods or commas (punctuation)

  • carrots
  • potatoes
  • cabbages

By contrast, a nonparallel list could look like this:

  • carrots
  • potatoes
  • The summer light obscures all memories of winter.

Start numbered list items with imperative verbs

Imperative verbs are commands, such as open or start. Consider starting all items in a numbered list with an imperative verb. For example:

âś…

  1. Download the Frambus app from Google Play or iTunes.
  2. Configure the Frambus app’s settings.
  3. Start the Frambus app.

đźš«

  1. Instantiate the Froobus class.
  2. Invoke the Froobus.Salmonella() method.
  3. The process stalls.

Introduce each list and table

It’s good practice to introduce lists and tables. A good practice is putting the word following into the introductory sentence. Examples:

The following list identifies key performance parameters:

Take the following steps to install the Frambus package:

The following table summarizes our product’s features against our key competitors’ features:

Paragraphs

Good opening sentences establish the paragraph’s central point. For example, the following opening sentence establishes the theme of the paragraph as an introduction to loops:

A loop runs the same block of code multiple times. For example, suppose you wrote a block of code that detected whether an input line ended with a period. To evaluate a million input lines, create a loop that runs a million times.

Focus each paragraph on a single topic

A paragraph should represent an independent unit of logic. Restrict each paragraph to the current topic. Don’t describe what will happen in a future topic or what happened in a past topic. When revising, ruthlessly delete (or move to another paragraph) any sentence that doesn’t directly relate to the current topic.

Don’t make paragraphs too long or too short

Long paragraphs are visually intimidating. Very long paragraphs form a dreaded “wall of text” that readers ignore. Readers generally welcome paragraphs containing three to five sentences, but will avoid paragraphs containing more than about seven sentences.

Answer what, why, and how

  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?

Example:

[What:] The garp() function returns the delta between a dataset’s mean and median. [Why:] Many people believe unquestioningly that a mean always holds the truth. However, a mean is easily influenced by a few very large or very small data points. [How:] Call garp() to help determine whether a few very large or very small data points are influencing the mean too much. A relatively small garp() value suggests that the mean is more meaningful than when the garp() value is relatively high.

Audience

Define your audience

Things to consider when defining your audience:

  • Are you writing the document to software engineers? Product managers? Both?
  • What’s the proximity to the knowledge? Example: Engineers who worked on project Frambus know things about project Dingus, but nothing about project Carambola.

Fit documentation to your audience

  • Be mindful of proximity. The people on your team probably understand your team’s abbreviations, but do people on other teams understand those same abbreviations?
  • Unless you are writing specifically for other experienced members of your team, you typically must explain more than you expect.
  • Curse of knowledge. As experts, it is easy to forget that novices don’t know what you already know.
  • Prefer simple words over complex words. English is not the native language of a significant percentage of technical readers.
  • Keep your writing culturally neutral. Avoid things like baseball metaphors (common in American English) or other localised idioms. Examples: “piece of cake”, “Bob’s your uncle”, “off the bat”.

Summary

  • Use terms consistently.
  • Avoid ambiguous pronouns.
  • Prefer active voice to passive voice.
  • 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.
  • Start numbered list items with imperative words.
  • Introduce lists and tables appropriately.
  • Create great opening sentences that establish a paragraph’s central point.
  • Focus each paragraph on a single topic.
  • Determine what your audience needs to learn.
  • Fit documentation to your audience.
  • Establish your document’s key points at the start of the document.