Words

Introduction permalink

Originally this was the first of several posts about the Technical Writing course provided by Google. I have amalgamated all posts on this topic together into this post. Each post has an introduction section which explains what will be covered until the next introduction section.

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.

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:

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.

Active Voice

Introduction permalink

This is the second of several posts about the Technical Writing course provided by Google. They will each be tagged Technical Writing.

This particular post covers the third unit:

3 - Active Voice

The course itself goes in to more detail in each topic, these notes aim to be a brief review in order to better fortify the concepts covered.

Active Voice permalink

Sentences in technical writing should usually be written in active voice.

How to Distinguish Active Voice from Passive Voice permalink

In an active voice sentence, an actor acts on a target. In a passive voice sentence this formula is reversed.

See the two formula below, followed by a basic example of each:

Active Voice:
actor + verb + target
'The cat sat on the mat.'

Passive Voice:
target + verb + actor
'The mat was sat on by the cat.'

In each example the actor, the verb and the target remain the same:

Actor: the cat
Verb: (was) sat
Target: the mat

The passive voice can also sometimes omit the actor. In this case the actor is unknown. Eg: The mat was sat on.

Omission of the actor can lead to a sentence being amiguous - in this case the reader is unaware of who sat on the mat. It may have been a dog, or any other animal. Good technical writing will be clear about who is doing an action.

How to Recognise Passsive Verbs permalink

A passive verb will usually be made up of a form of be and the past participle verb. To make sense of that, you can break it down further:

• A form of be will typically be:
  • is / are
  • was / were
• The past participle verb will typically be the plain verb plus the suffix ed. Some examples are:
  • interpreted
  • generated
  • formed

There are also some irregular past participle verbs. In these cases the past participle form does not end with ed. Some examples are:

• sat
• known
• frozen

Some of the same examples as passive verbs are:

• was interpreted
• is generated
• was formed
• is frozen
• are known

If the phrase does contain an actor, a preposition ordinarily follows the passive verb. For example:

• was interpreted as
• is generated by
• was formed by

Imperative Verbs are Typically Active permalink

An imperative verb is a command. Sentences that start with an imperative command are typically in active voice. They can often be confused as passive though because they do not usually contain an actor - however, the use of an imperative verb implies an actor. The implied actor is you.

A usual example of active voice with an imperative verb is in a list:

1 - Open the configuration file

2 - Set the Frombus variable to False.

Some Examples permalink

These images are taken directly from the course website (I hope google do not mind...):

Use Active Voice More Often than Passive Voice permalink

Active voice should be used most of the time. Passive voice should be used sparingly. Active voice has a few advantages for writers and readers:

• Most readers will mentally convert passive voice to active voice in order to better understand. Sticking to active voice removes this processing time for readers.
• Passive voice reports action indirectly. In doing so, it obfuscates the presented ideas.
• Passive voice can omit the actor altogether which forces the reader to guess critical information which could have been provided to them if the active voice had been used.
• Generally active voice is shorter than passive voice.

Be bold — be active.

Clear Sentences

Introduction permalink

This is the third of several posts about the Technical Writing course provided by Google. They will each be tagged Technical Writing.

This particular post covers the unit:

Clear Sentences

The course itself goes in to more detail in each topic, these notes aim to be a brief review in order to better fortify the concepts covered.

Clear Sentences permalink

Comedy writers seek the funniest results, horror writers strive for the scariest, and technical writers aim for the clearest. In technical writing, clarity takes precedence over all other rules. This unit suggests a few ways to make your sentences beautifully clear.

The aim in technical writing is to 'show the thing' ↗.

Clarity takes precedence over style and 'all other rules' - to ensure clarity you should not dress up the thing you are presenting. Don't use metaphors, and explain clearly what the thing is and how it works.

Choose Strong Verbs permalink

The verb can be the most important part of a sentence. Choosing the correct verb allows the rest of the sentence to take care of itself. Take a little more time while writing to pick the right verb for the situation and your writing will yield more satisfying results than sticking to a small set of safe and widely re-used verbs.

Some examples of widely used and repeated verbs are:

• forms of be: is, are, am, was, were etc.
• occur
• happen

And some examples of switching these for a stronger, more precise, verb are:

Reliance on forms of be is very common in writing. Using different verbs can help your writing to be more direct, readable and informative. However, remember that a form of be is sometimes the best choice of verb - it does not need to be eliminated completely from your writing.

Note: Generic verbs may also be a signal of other issues with your writing. They can indicate an imprecise or missing actor in a sentence, or a passive voice sentence.

Examples

1 When a variable declaration doesn't have a datatype, a compiler error happens.

2 Compiler errors occur when you leave off a semicolon at the end of a statement.

⬇

1 "When a variable declaration does not specify a datatype the compiler generates an error."

2 "A missing semicolon at the end of a statement triggers a compiler error."

Reduce There is / There are permalink

Using There is or There are at the beginning of a sentence can sometimes be simply unneccessary, and at other times be too generic. For example:

There is a variable called met_trick that stores...

In this situation There is can be removed by simply referring directly to the variable:

A variable called met_trick stores...

In a different situation removing the There are can be achieved by moving the true subject and true verb from the end to the beginning:

There are two disturbing facts about Perl you should know.

You should know two disturbing facts about Perl.

Or in some cases the inclusion of There is or There are means the sentence is omitting the true subject or verb. In this situation, consider creating a subject:

There is no guarantee that the updates will be received in sequential order.

Clients may not receive the updates in sequential order.

Minimise Certain Adjectives and Adverbs permalink

Adjectives and adverbs have their place in language and writing - they perform very well in fiction, poetry, drama and speech for example.

Thanks to adjectives, plain old grass becomes prodigal and verdant, while lifeless hair transforms into something silky and flowing. Adverbs push horses to run madly and freely and dogs to bark loudly and ferociously.

They do not perform so well in technical writing. In general they are too loosely defined and subjective to be useful for technical readers. Their use can make technical writing read too much like marketing material.

The example and explanation which the Google training module uses is:

Setting this flag makes the application run screamingly fast.

"Granted, screamingly fast gets readers attention but not necessarily in a good way. Feed your technical readers factual data instead of marketing speak. Refactor amorphous adverbs and adjectives into objective numerical information."

Setting this flag makes the application run 225-250% faster.

"Does the preceding change strip the sentence of some of its charm? Yes, a little, but the revamped sentence gains accuracy and believability."

Short Sentences

Introduction permalink

This is the fourth of several posts about the Technical Writing course provided by Google. They will each be tagged Technical Writing.

This particular post covers the unit:

Short Sentences

The course itself goes in to more detail in each topic, these notes aim to be a brief review in order to better fortify the concepts covered.

Short Sentences permalink

In software engineering keeping the number of lines of code to the minimum possible is generally positive because:

• Shorter code is typically easier for others to read.
• Shorter code is typically easier to maintain than longer code.
• Extra lines of code introduce additional points of failure.

Technical writing is similar in the following respects:

• Shorter documentation reads faster than longer documentation.
• Shorter documentation is typically easier to maintain than longer documentation.
• Extra lines of documentation introduce additional points of failure.

ℹ Both of the above lists are taken directly from the google course page ↗.

Reaching the shortest possible documentation may take extra time. It is worthwhile though. Short sentences communicate better than longer ones, and they are usually easier to understand.

Focus Each Sentence on a Single Idea permalink

A single idea, thought or concept is enough for each sentence. Each task in a program should ideally be executed by a single statement. The same formula should be followed in technical writing.

Google's examples:

A sentence containing multiple thoughts / ideas:
"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 same sentence broken into a succession of single idea sentences:
"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 permalink

Often a long sentence can be broken into a list instead. This is especially true in technical writing. 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)."

If ever a long sentence contains the conjunction or, you should consider refactoring the sentence into a bulleted list. If a longer sentence includes a list of items or tasks, you should consider refactoring the sentence into a bulleted or numbered list. For example:

"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 permalink

Sentences often contain filler. The same meaning can often be conveyed with a few less words.

A good example of this is:

This design document provides a detailed description of Project X.

This sentence can loose four whole words (and alter one slightly) and mean exactly the same thing:

This design document details Project X.

Below are some more examples of concise alternatives to wordy phrases. This is a non-exhaustive list. Find the meaning of the phrase and see if it can be conveyed in one or two words, often it can.

Reduce Subordinate Clauses permalink

Sentences regularly contain one or more subordinate clauses. A clause is an independent fragment of a sentence which contains an actor and an action. Every sentence has a main clause, and can then contain zero or more subordinate clauses.

Python is an interpreted programming language, which was invented in 1991.

main clause: "Python is an interpreted programming language"
subordinate clause: "which was invented in 1991"

In some short sentences subordinate clauses can be helpful, but not in all. When writing, or editing, keep the idea that one sentence should contain one idea in mind. Does the subordinate clause extend the single idea, or does it branch off to another idea? Consider dividing the subordinate clause into a separate sentence if it contains a separate idea.

Some words which often introduce subordinate clauses in sentences:

• which
• that
• because
• whose
• until
• unless
• since
• ...

A more complex example (containing multiple clauses):

"Bash is a modern shell scripting language that takes many of its features from KornShell 88, which was developed at Bell Labs."

The first subordinate clause extends the main idea, but the second subordinate clause goes in another direction. Below the sentence is divided in two, with the main clause in bold and the relevant subordinate clause in emphasis.

Bash is a modern shell scripting language that takes many of its features from Kornshell 88. Bash was developed at Bell labs.

That and Which

To avoid confusion around different conventions in the English language (British, American and translations) that should be used for restrictive clauses, and which for non-restrictive clauses. A restrictive clause is an essential subordinate clause - the sentence can't live without it. A non-restrictive clause is the opposite - the sentence will still be fine without the subordinate clause.

The example which Google gives in the lesson is the following:

Python is an interpreted language, which Guido van Rossum invented.

"Python is an interpreted language." - This sentence is fine without the above subordinate clause.

And in contrast:

Fortran is perfect for mathematical calculations that don't involve linear algebra.

"Fortran is perfect for mathematical calculations." - This sentence means something different from the one above.

Another example using one of the previous examples but re-arranged:

Bash is a modern shell scripting language, which was developed at Bell labs. Bash takes many of its features from Kornshell 88.

You can also usually place a comma before the use of which, but not before the use of that.

Lists and Tables

Introduction permalink

This is the fifth of several posts about the Technical Writing course provided by Google. They will each be tagged Technical Writing.

This particular post covers the unit:

Lists and Tables

The course itself goes in to more detail in each topic, these notes aim to be a brief review in order to better fortify the concepts covered.

Lists and Tables permalink

Types of Lists permalink

Generally a list will read easier than prose. This is especially true in a technical context.

There are three types of list which are regularly used in technical writing:

• Bulleted lists
• Numbered lists
• Embedded lists

A bulleted list is used for unordered items. A numbered list is used for ordered items.

• Rearranging the items in a bulleted list does not change the list's meaning.
• Rearranging the items in a numbered list does change the list's meaning.

Examples:

Bash provides the following string manipulation mechanisms:

• deleting a substring from the start of a string
• reading an entire file into one string variable

Take the following steps to reconfigure the server:

1. Stop the server.
2. Edit the configuration file.
3. Restart the server.

An embedded list contains items within a sentence.

Example:

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

Generally, an embedded list is not a great way to present technical information. Transforming an embedded list into a bulleted or numbered list usually provides a more clear way for the information to be processed by the reader. For example:

The llamacatcher API enables callers to do the following:

• Create and query llamas.
• Analyze alpacas.
• Delete vicugnas.
• Track dromedaries.

Parallel List Items permalink

Keeping list items parallel with one another ensures that list will be effective. Defective lists tend to include nonparallel items. Items in a parallel list will match along the following parameters:

• grammar
• logical category
• capitalisation
• punctuation

Examples:

Parallel list items:

• carrots
• potatoes
• cabbages

Nonparallel list items:

• carrots
• Potatoes.
• The summer light obscures all memories of winter,

"The first item in the list establishes a pattern that readers expect to see repeated in subsequent items."

Google Technical Writing ↗

Numbered Lists and Imperative Verbs permalink

A numbered list can often have each item begin with an imperative verb. An imperative verb is a command, such as open or start.

Example:

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

Example of a nonparallel numbered list (two items begin with an imperative verb, the third does not):

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

Punctuate List Items permalink

For a complete sentence, use capitalisation and punctuation. Otherwise do not. However, within each list, be consistent (as covered above).

Example:

• Most carambolas have five ridges.

• the colour of lemons

Useful Tables permalink

When there is a choice between reading multiple paragraphs or reading the key information in a table, many analytical minds will choose to use the table to find out what they need to know.

Some guidelines for creating tables:

• Label each column with a meaningful header. Don't make the reader guess what that column holds.
• Avoid putting too much text into a table cell. If a table cell holds more than two sentences, ask yourself whether that information belongs in another format.
• Although different columns can hold different types of data, strive for parallelism within individual columns. For instance, the cells within a particular table column should not be a mixture of numerical data and famous circus elephants*.

*Taken directly from Google's training page! 🐘

Introduce Lists and Tables permalink

A short and well written introduction for each list and table tells the reader what the list or table represents. It will give the reader context for the list or table. The sentence can be terminated with a colon instead of a full-stop.

Use of the word following is regularly appropriate. For example, consider the following introductory sentences:

The following list identifies key performance parameters:

Take the following steps to install the Frambus package:

The following table summarises our product's features:

The following table is an example of an effective table: