Procedures

Introductory sentences

In most cases, introduce a procedure with an introductory sentence. This introductory sentence should provide context to the reader that isn't part of the section heading. Don't simply repeat the heading: if the heading explains what the procedure is, and no additional context is needed, then don't include an introductory statement.

The sentence can end with a colon or a period. Use a colon if it immediately precedes the procedure. Use a period if there's more material (such as a note paragraph) between the introduction and the procedure.

You can introduce a procedure with an imperative statement. Don't introduce a procedure with a partial sentence that's completed by the numbered steps.

Recommended: To customize the buttons, follow these steps:

Also recommended: Customize the buttons:

Not recommended: To customize the buttons:

Single-step procedures

When a procedure consists of only one step, write the step in one sentence and format it as a bulleted list.

Recommended:

  • To clear (flush) the entire log, click Clear logcat.

Not recommended:

To clear (flush) the entire log, follow this step:

  1. Click Clear logcat.

Also not recommended:

To clear (flush) the entire log, follow this step:

  • Click Clear logcat.

Sub-steps in numbered procedures

In a numbered procedure, sub-steps are labeled with lowercase letters, and sub-sub-steps get lowercase Roman numerals.

When a step has sub-steps, treat the step like an introductory sentence: put a colon or a period at the end of the step, as appropriate.

Recommended:

  1. To add a VM instance, do the following:
    1. Click Create instance.
    2. Enter a Name for the VM instance, and then do the following:
      1. Select the Region where you want to deploy the VM instance.
      2. Select the Machine type.
    3. Click Create.
  2. To connect to the VM instance by using SSH, click SSH.

Multi-action procedures

In general, use one step per action. However, you can combine small actions into one step by using angle brackets (>) for sequential menu selections.

Recommended:

  1. Click Next > Finish.

Also recommended:

  1. Click File > New > Document.

Don't make the steps too long. If they feel too long, consider splitting them into multiple steps.

Multiple procedures for the same task

In general, if there is more than one way to complete a task, pick one procedure to document that is accessible for all users. If all of the procedures need to be documented, use separate headings or pages or tabs to separate the procedures to make it clear to the reader that this is an alternative way to complete the same task.

The following guidelines can help you choose which procedure to document:

  • Choose a procedure that lets readers do all the steps by using only a keyboard.
  • Choose the shortest procedure.
  • Choose a procedure that uses a programming language that the majority of your audience is familiar with.

Repetitive procedures

Use concise procedures to avoid repetitiveness and overwhelming the user with too much bolding of UI elements.

Recommended:

  1. Click Enter.
  2. In the New File dialog that appears, click Next.

Not recommended:

  1. Click Enter. The New File dialog appears.
  2. In the New File dialog, click Next.

Avoid repeating procedures. Instead, reference those procedures and link to them.

Recommended:

  1. Create a user as you did in the previous step.

Also recommended:

  1. Create a user as you did in the previous step.

More guidelines for writing procedures

Guidance Recommended Not recommended
Make sure that the first sentence in a procedural step includes an imperative verb. Clone the repository that contains the sample data. You need the project ID later in this document. Retrieve the project ID.
Use complete sentences.
Use parallel structure.
For an optional step, type Optional: as the first word of the step. Optional: Type an arbitrary string... (Optional) Type an arbitrary string...

Set the context (such as a tool or an environment) in which the user performs a procedure.

If there are multiple headings associated with a set of procedures, restate the context of the procedure in the first step, even if the context is the same as in the previous procedure.

In Cloud Shell, connect to the development cluster.

In the Cloud Console, go to the BigQuery page.

Write in the order that the reader needs to follow. State the location of the action before stating the action.

In Google Docs, click File > New > Document.

In the Google Cloud Console, go to the Monitoring page.

Click File > New > Document in Google Docs.

Go to the Monitoring page in the Google Cloud Console.

State the purpose or goal of the action before stating the action. To start a new document, click File > New > Document. Click File > New > Document to start a new document.

Don't use directional language to orient the reader, such as above, below, or right-hand side. This type of language doesn't work well for accessibility or for localization. If a UI element is hard to find, provide a screenshot.

For information about documenting icons, see Buttons and icons.

Click Menu.

In the preceding diagram,...

In the following diagram,...

Click the button with three lines.

In the above diagram, ...

In the diagram below, ...

Don't use please. To open a document, click File > Open. To open a document, please click File > Open.
Avoid using run the following command to introduce code. Instead, focus on what the command does.

In Cloud Shell, deploy the load generator:...

Define a firewall rule to allow internal traffic:...

In Cloud Shell, deploy the load generator by running the following command:...

Run the following command:...

If the user must press Enter after a step, then include that instruction as part of the step. Click the search box, type custom function, and then press Enter.
  1. Click the search box and type custom function.
  2. Press Enter.
Don't include keyboard shortcuts. Copy the command, and then paste it... Press Ctrl+C, and then press Ctrl+V...
When there's more than one way to do something, give only the best way. Giving alternate ways can confuse users.