Steps and lists

Steps are also known as procedures or tasks. They answer “How do I?” questions. They have a well-defined structure that describes how to complete a procedure to accomplish a specific goal. The task follows the concept.

What’s in a task?

Task information includes:

  • Navigation
  • Screens
  • Interface elements to click or complete to accomplish the task
  • Field/option descriptions
  • Use UICONTROL with bold when referring to interface elements in a task. (See Localization for more.)

Headings for procedures (task headings)

You can design procedural (task) and conceptual information in two ways, depending on scale:

  • For large features, use a parent concept page with child task pages.
  • For small features, use a single page with a concept heading and task subheadings

For a conceptual page with child tasks, use a noun phrase for the conceptual title, then imperative verbs for child tasks.

Example:

Experience Cloud audiences (concept page)
 Create an audience (task page)
 Share an audience to Adobe Analytics (task page)

Tips and guidelines for a procedure

Use these guidelines when writing a procedure:

  • Use sentence style capitalization for a task heading.

  • Begin with a verb. However, if necessary, mention the goal (“To”) before the action:

    Example: “To run the report, click Run.” (This affects Acrolinx Style scores.)

  • Add conceptual information (including prerequisites) before the steps. (Most conceptual information should reside in the overview preceding the task, but some tasks require contextual conceptual information.) If you find yourself adding more than a paragraph of conceptual information before the steps in a task, create a concept heading.

  • Write a step a single command that contains only one sentence. Extra information (step results, images, information about the step) must go on the next line. (See Complex procedures on this page.)

  • Images: Store graphics (screenshots, process graphics) in the Assets folder in the guide, and link to the asset (using Markdown syntax).

Describing the interface

It’s important to know the words to use to describe interactions with the interface.

  • Open: Applications and programs. “Open the Segments panel.”
  • Close: Applications and programs. “Close the Dimensions window.”
  • Leave: Websites and pages. “Leave Report Builder.”
  • Go to: “From the File menu,” “Go to the File menu,” “On the Reports tab” (Go to a tab or place in the UI)
  • Select: Select a value from a list. Select a checkbox.
  • Click: “Click XYZ.” Note the following best practices for click:
    • Avoid calling out the control type (“Click the XYZ button”) unless knowing the control type is important for clarity. (Control types can change over time during development. The control’s name, if visible, is adequate.)
    • Click is device-specific. The trend is to use select if your docs apply to multiple device input types.

See Describing Actions in the UI in the Microsoft® Manual of Style for guidance.

Complex procedures

Complex procedures include multiple steps and perhaps bullets and sub-steps. For multiple-step procedures in numbered lists:

  • Format procedures consistently so customers can find them easily by scanning.

  • Consider using a brief step heading (a “To” heading) to help customers find instructions quickly, especially if there are paragraphs preceding it (between the main task heading and the steps). Use the step heading to tell customers what the instructions help them do.

    Example step headings:

    • To create an Experience Cloud Trigger

    • Create an Experience Cloud Trigger

      This heading should closely mirror the task’s main heading.

  • Choose one phrasing style for the headings, and write them all the same way (in parallel structure).

  • Use a separate numbered entry for each step. It’s OK to combine short steps that occur in the same place in the UI.

  • Most of the time, include actions that finalize a step, such as OK or Apply buttons.

  • Use complete sentences.

  • Use imperative verb forms. In instructions, customers want explicit commands.

  • Use consistent sentence structures. For example, always use a phrase when you need to tell the customer where to start. The rest of the time, start each sentence with a verb. (Goal before action.)

    Examples:

    • On the Calendar panel, click Today.
    • To specify a date, click Calendar.
    • For Alignment, choose Left.
  • Capitalize the first word in each step.

  • Include only the command in the step. Information about the step goes on a separate, intended line.

  • Use a period after each step.

    Exception:

    • When instructing customers to type input that doesn’t include end punctuation, don’t use a period. Format the text so that the user input appears on a new line.
  • Limit a procedure to seven steps, and preferably fewer. Try to fit all the steps on the same screen.

Sample complex procedure.

Single-step procedures

If you’re using a consistent format for step-by-step instructions, use the same format for single-step instructions, but replace the number with a bullet.

Fields and options

Document the navigation to (and definitions for) interface elements in Task (steps) content types. If you find yourself doing including steps in a concept, overview, FAQ, or anywhere outside of the procedure, the information is in the wrong place.

Use bold UICONTROL for interface elements so that readers can scan for this information. When they find the bold UI element name, everything they need to know about the UI element should be in the definition, or nearby it (in the step).

Sample step with field descriptions:

field descriptions

Lists

Lists present complex text in a way that’s easy to scan.

Lists work best when they have two to seven items. Each item should be fairly short—the reader should be able to see at least two, and preferably three, list items at a glance. It’s OK to have a couple of short paragraphs in a list item, but don’t exceed that length too often.

Make items in a list parallel. For example, each item should be a noun or a phrase that starts with a verb.

Bullet lists

Use a bulleted list for things that have something in common but don’t need to appear in a particular order.

Example
The database owner can:

Create and delete a database.
Add, delete, or modify a document.
Add, delete, or modify any information in the database.

Numbered (ordered) lists

Use a simple numbered list for sequential items (like a procedure) or prioritized items (like a top ten list). A numbered list differs from a complex procedure (described above), which contains extra information (screens, interface element descriptions, and so on.)

On this page