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.
"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 following learning outcomes:
- Understand the difference between bulleted lists and numbered lists.
- Create helpful lists.
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.
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:
- Stop the server.
- Edit the configuration file.
- Restart the server.
An embedded list contains items within a sentence.
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:
- logical category
Parallel list items:
Nonparallel list items:
- 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.
- Download the Frambus app from Google Play or iTunes.
- Configure the Frambus app's settings.
- Start the Frambus app.
Example of a nonparallel numbered list (two items begin with an imperative verb, the third does not):
- Instantiate the Froobus class.
- Invoke the Froobus.Salmonella() method.
- 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).
- Most carambolas have five ridges.
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:
|Language||Inventor||Year Introduced||Key Feature|
|Python||Guido van Rossum||1994||simplicity|