'Words' - Technical Writing One - Google

— 6 minute read

Introduction permalink

This will be the first of several posts about the Technical Writing course provided by Google. Together they will form a general overview of the course. They will each be tagged Technical Writing.

This particular post covers the first two units:

1 - Just Enough Grammar (Optional Unit)

2 - Words

The course itself goes in to more detail in each topic, but these notes aim to be a brief review in order to better fortify the concepts covered. There is also an in-class component which will not be covered here.

Learning Outcomes

"Technical Writing One teaches you how to write clearer documentation."

According to the welcome page this course teaches the fundamentals of technical writing.

This post covers the first two learning outcomes:

  • Use terminology consistently.
  • Recognize and disambiguate pesky pronouns.

Just Enough Grammar (Optional Unit) permalink

An optional unit which covers the parts of speech and grammar relevant to the course.

It includes a short explanation and exercise for each of the following:

Part of speechDefinitionExample
NounA person, place, concept or thingSam runs races
PronounA noun that substitutes for another nounHe likes to compete
AdjectiveA word or phrase that modifies a nounSam wears blue shoes
VerbAn action word or phraseSam runs races
AdverbA word or phrase that modifies a verb, an adjective, or an adverbSam runs slowly
PrepositionA word of phrase specifying the positional relationship of two nounsSam's sneakers are seldom on his shelf
ConjunctionA word or phrase that connects two phrasesSam's trophies and ribbons live only in his imagination
TransitionA word or phrase that connects two sentencesSam runs races weekly. However he finishes races weakly.

The explanations and exercises for each are short and informative. They are worth the 5 - 10 minutes it takes to read this section.

Words permalink

Words are the most important part of any writing. This is no different in technical writing and documentation.

This section of the course directs the reader on how they should correctly:

1. Define new or unfamiliar terms

You should be able to recognise when a term may be unfamiliar to all or some of your target audience and then define that term in one of two ways:

  • If it already exists, link to a good existing explanation.
  • If the document you are writing is introducing the term, define the term.

If the document you are writing is introducing many terms, collect the definitions into a glossary.

2. Use terms consistently

You should always apply the same unambiguous word or term consistently throughout your document. If you are introducing a term, be consistent with the use of that term.

For example if your document introduces the term floober, continue to use that term throughout - do not begin referring to the same item or concept as a flub later on.

If you are clear when introducing a term (floober) that it is also known by a shortened name (flub), then you may use that shortened name throughout the rest of the document.

"Floobers (or flubs for short) are a state of mind..."

3. Use acronyms properly

On initial use of an acronym, use the full term, followed by the acronym in parentheses. Use emphasis, such as bold, on both the term and the acronym.

"A Three Letter Acronym (TLA) is an acronym that uses three letters."

You may then use the acronym throughout the rest of the document. However, you should also first assess if an acronym is needed.

Acronyms are a level of abstraction ↗. Readers must mentally expand recently learned acronyms to the full term to make sense of it. Because of this, if it is not necessary to create an acronym you should not do it.

The course gives the following guidelines for using (or not using) acronyms:

  • Don't define acronyms that would only be used a few times.
  • Do define acronyms that meet both of the following:
    • The acronym is significantly shorter than the full term.
    • The acronym appears many times in the document.

4. Disambiguate pronouns

Using a pronoun is a way of pointing to a previously introduced noun. Improper use of a pronoun can cause your writing to be difficult to interpret by the reader.

In many cases you can simply avoid using a pronoun and reuse the original noun. That is not always the case though:

The utility of a pronoun sometimes outweighs its risk (as in this sentence).

In general you should:

  • Only use a pronoun after you've introduced the noun. Never use a pronoun before introducing the noun.
  • Place the pronoun as close as possible to the referring noun. If more than five words seperate your noun and pronoun, you should instead consider repeating the noun.
  • If introducing a second noun between the first noun and pronoun, reuse the original noun instead of using a pronoun.

1 - 'It' and 'They', 'Them' and 'Their'

These can cause a lot of confusion in technical writing. Here are two examples taken directly from the course:

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.

In the first example the use of the pronoun (in bold) could be referring to either of the other nouns. Similarly, in the second example the pronoun could be referring to either group of previously mentioned nouns.

2 - 'This' and 'That'

Use of 'this' and 'that' as pronouns can lead to ambiguous sentences. Replacing the use of 'this' or 'that' with the appropriate noun, or placing the appropriate noun immediately after the use of 'this' or 'that' can help to disambiguate sentences.

This text is ambiguous:

You may use either Frambus or Foo to calculate derivatives. This is not optimal.

The following two texts include the appropriate noun to disambiguate the meaning of the text:

You may use either Frambus or Foo to calculate derivatives. Overlapping functionality is not optimal.

You may use either Frambus or Foo to calculate derivatives. This overlapping functionality is not optimal.