Procedures

Introductory sentences

In most cases, introduce a procedure with an introductory sentence. The sentence can end with a colon or a period; usually a colon if it immediately precedes the procedure, usually a period if there's more material (such as a note paragraph) between the introduction and the procedure.

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:

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. First, do foo, as follows:
    1. Do the first part of foo.
    2. Do the second part of foo. There is no third part.
      1. Do the first sub-part of foo part two.
      2. Do the second sub-part of foo part two.
  2. Next, do bar.

More guidelines for writing procedures

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

    Recommended:

    1. Click Next > Finish.

    Also recommended:

    1. Click File > New > Document.

  • Don't make the procedure too long. If it starts to feel too long, consider splitting it into two 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 or location 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.

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

Enviar comentarios sobre…

Google Developer Documentation Style Guide
Google Developer Documentation Style Guide