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.

Not recommended: To customize the buttons:

Recommended: To customize the buttons, follow these steps:

Also recommended: Customize the buttons:

Single-step procedures

When a procedure consists of just one step, fold the step into the introductory sentence.

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.

Recommended:

To clear (flush) the entire log, 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, 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 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.

Not recommended:

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

Recommended:

  1. Click Enter.
  2. In the New File dialog that appears, 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

  • If the user must press Enter after a step, then include that instruction as part of the step.

    Not recommended:

    1. Click the search box in the top-right corner and type custom function.
    2. Press Enter.

    Recommended:

    1. Click the search box in the top-right corner, then type custom function and press Enter.

  • State the purpose of the action before stating the action.

    Not recommended:

    1. Click File > New > Document to start a new document.

    Recommended:

    1. To start a new document, click File > 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.

    Not recommended:

    1. Click File > New > Document in Google Docs.

    Recommended:

    1. In Google Docs, click File > New > Document.

  • Don't use "please."

    Not recommended:

    1. To open a document, please click File > Open.

    Recommended:

    1. To open a document, click File > Open.

  • For an optional step, type "Optional:" as the first word of the step.

    Recommended:

    1. Optional: Type an arbitrary string, to be delivered to the target address with each notification delivered over this channel.

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

    Not recommended: In the left-side panel, click the button with three lines.

    Recommended: Click Menu .