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.
To create numbered lists (steps and sub-steps), begin a line with
1.. You don’t need to specify the numbers. GitHub does that for you.
Use the number
1 for every step in the numbered list.
Add blank lines before and after lists. Indent the next line to create a sub-step.
1. This is step 1. 1. This is the next step. 1. This is a sub-step 1. This is a sub-step 1. This is yet another step, the third.
See Numbered lists and bullet lists for syntax information.
Task information includes:
You can design procedural (task) and conceptual information in two ways, depending on scale:
For a conceptual page with child tasks, use a noun phrase for the conceptual title, then imperative verbs for child tasks.
Experience Cloud audiences (concept page) Create an audience (task page) Share an audience to Adobe Analytics (task page)
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).
It’s important to know the words to use to describe interactions with the interface.
See Describing Actions in the UI in the Microsoft® Manual of Style for guidance.
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.)
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.
Limit a procedure to seven steps, and preferably fewer. Try to fit all the steps on the same screen.
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.
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:
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.
Use a bulleted list for things that have something in common but don’t need to appear in a particular order.
The database owner can:
Create and delete a database.
Add, delete, or modify a document.
Add, delete, or modify any information in the database.
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.)