Lists and Tables

Lists and Tables

Choose the correct type of list

Types of lists and their use cases:
  • Use Numbered lists for ordered items.
  • Use Bullet lists for unordered items.
  • Use embedded lists sparingly.
    • Example: The llama catcher API enables callers to create and query llamas, analyse alpacas, delete vicunas, and track dromedaries.
      Note: This would still be better as a bulleted list as it doesn’t look presentable as is.
Exercise
Today at work, I have to code three unit tests, write a design document, and review Janet's latest document. After work, I have to wash my car without using any water and then dry it without using any towels.
My Attempt
I have to do the following today:
  • At work:
    • Code three unit tests.
    • Write a design document.
    • Review Janet’s latest document.
  • After work:
      1. Wash my car without using any water.
      1. Dry it without using any towels.
Damn, I later learnt from the Google solution that I should use “I must” instead of “I have to” .
Answer by Google
Here's one possible answer:
I must do the following at work today:
  • Code three unit tests.
  • Write a design document.
  • Review Janet's latest document.
After work, I must do the following:
  1. Wash my car without using any water.
  1. Dry my car without using any towels.
The following is an alternative answer:
I must do the following tasks today:
  • At work:
    • Code three unit tests.
    • Write a design document.
    • Review Janet's latest document.
  • After work:
      1. Wash my car without using any water.
      1. Dry my car without using any towels.

Keep list items parallel

Effective lists are parallel i.e. they look like they belong together. All items in a parallel list match along the following parameters:
  • Grammar
  • Logical category
  • Capitalization
  • Punctuation
Examples by Google
Parallel list
The following list is parallel because all the items are plural nouns (grammar), edible (logical category), in title case (capitalization), and without periods or commas (punctuation).
  • Carrots
  • Potatoes
  • Cabbages
Non-Parallel list
By contrast, the following list is painfully nonparallel along all parameters:
  • Carrots
  • Potatoes
  • The summer light obscures all memories of winter.
Parallel list
The following list is parallel because all the items are complete sentences with complete sentence capitalization and punctuation:
  • Carrots contain lots of Vitamin A.
  • Potatoes taste delicious.
  • Cabbages provide oodles of Vitamin K.
 
Exercises by Google
  1. Is the following list parallel or nonparallel?
  • Broccoli inspires feelings of love or hate.
  • Potatoes taste delicious.
  • Cabbages.
 
  1. Is the following list parallel or nonparallel?
  • The red dots represent sick trees.
  • Immature trees are represented by the blue dots.
  • The green dots represent healthy trees.
My Attempt
  1. Nonparallel
  1. Parallel
Answer by Google
  1. The list is nonparallel. The first two items are complete sentences, but the third item is not a sentence. (Don't be fooled by the capitalization and punctuation of the third item.)
  1. This is a nonparallel list. The first and third items are in active voice, but the second item is in passive voice.

Start numbered list items with imperative verbs

Consider starting all items in a numbered list with an imperative verb. An imperative verb is a command e.g. open or start.
Examples by Google
Notice how all of the items in the following parallel numbered list begin with an imperative verb:
  1. Download the Frambus app from Google Play or iTunes.
  1. Configure the Frambus app's settings.
  1. Start the Frambus app.
 
The following numbered list is nonparallel because two of the sentences start with an imperative verb, but the third item does not:
  1. Instantiate the Froobus class.
  1. Invoke the Froobus.Salmonella() method.
  1. The process stalls.
Exercise by Google
Make the following list parallel. Ensure that each element in the result list begins with an imperative verb:
  1. Stop Frambus
  1. The key configuration file is /etc/frambus. Open this file with an ASCII text editor.
  1. In this file, you will see a parameter named Carambola, which is currently set to the default value (32). Change this value to 64.
  1. When you are finished setting this parameter, save and close the configuration file
  1. now, start Frambus again.
My Attempt
  1. Stop Frambus.
  1. Open the key config file /etc/frambus with an ASCII text editor.
  1. Change the default value(32) of the Carambola parameter in the file to 64.
  1. Save and close the config file.
  1. Start Frambus again.
Answer by Google
The following is one possible answer:
  1. Stop Frambus.
  1. Open the key configuration file,/etc/frambus, with an ASCII text editor.
  1. Change the Carambola parameter from its default value (32) to 64.
  1. Save and close the configuration file.
  1. Restart Frambus.

Punctuate items appropriately

The Google developer documentation style guide recommends (with some exceptions) the following for list items:
  1. Start each list item with a capital letter.
  1. Use appropriate sentence-ending punctuation(for sentences).
Examples
Case 1:
  • Loops
  • Conditionals
  • Variable declarations
Case 2:
  1. Open the program.
  1. Click the settings icon.

Create useful tables

Consider the following when creating tables:
  • Meaningful headers: Label each column with a meaningful header. Readers shouldn’t have to guess the contents of a column.
  • Concise: If a table cell holds more than two sentences, ask yourself whether that info belongs in some other format.
  • Parallelism: The cells within a particular table column should not be a mixture of numerical data and famous actresses.
Note: Some tables don't render well across all form factors. For example, a table that looks great on your laptop may look awful on your phone.
Note: Some tables don't render well across all form factors. For example, a table that looks great on your laptop may look awful on your phone.

Introduce each list and table

Give the list or table context. Introduce them and try to end the introduction with a colon rather than a period.
Example
Although not a requirement, we recommend putting the word following into the introductory sentence. 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 summarizes our product's features against our key competitors' features:
Exercise
Write an introductory sentence for the following table:
Languages
Inventor
Year Introduced
Key Feature
Lisp
John McCarthy
1958
recursion
C++
Bjarne Stroustrup
1979
OOP
Python
Guido van Rossum
1994
simplicity
My Attempt
The following table summarizes programming languages and other key details about them:
Answer by Google
Here are a couple of possible introductory sentences for the table:
The following table contains a few key facts about some popular programming languages:
The following table identifies the inventor, year of invention, and key feature of three popular programming languages:
Â