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
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.
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.

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

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

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.

Don't use please. To open a document, click File > Open. To open a document, please click File > Open.
For an optional step, type Optional: as the first word of the step. Optional: Type an arbitrary string... (Optional) Type an arbitrary string...
Use complete sentences.
Use parallel structure.
When there's more than one way to do something, give only the best way. Giving alternate ways can confuse users.
Don't include keyboard shortcuts. Copy the command, and then paste it... Press Ctrl+C, and then press Ctrl+V...

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, ...