Steps and lists steps
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.
Steps in exercises are inherently similar to procedures in product documentation.
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.
Punctuation in lists
Don’t use semicolons, commas, or conjunctions (like and or or) at the end of list items.
Don’t use a period at the end of list items unless they’re complete sentences, even if the complete sentence is very short.
When to use punctuation
If the list is introduced by a sentence fragment that ends with a colon, end all the items in the list with a period if any item forms a complete sentence when combined with the introduction.
Examples
Product managers can:
- Confirm or remove topics that were discovered in your tenant.
- Create new topics manually as needed.
- Edit existing topic pages.
Exceptions
Don’t use periods if all items have three or fewer words or if the items are UI labels, headings, subheadings, strings, or similar types of text.
The files for upload customer attributes include:
- companylist.csv
- update.pdf
Authoring guidelines for a procedure step-guidance
Follow these guidelines when writing a procedure:
-
A step is a single, concise command. A step 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.)
-
Limit procedures to around seven steps. Generally, a procedure should not be more than seven numbered steps. Readers begin to lose interest or get fatigued beyond seven steps.
-
Begin with a verb. Use the imperative verb (for example, Create a segment.)
However, if necessary, mention the goal (“To”) before the action:
Example: To create a Fallout report, click New. (Acrolinx flags this.)
-
Keep conceptual information separate. 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 just prior to beginning. If you find yourself adding more than a paragraph of conceptual information before the steps, consider creating a concept heading for that information, then a task heading for the task.
-
Place screenshots after the step. A screenshot showing results should immediately follow the step.
-
Capitalization and punctuation. Capitalize the first word in each step. 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 text appears on a new, indented line.
Create steps in Markdown (syntax)
To create numbered lists (steps and sub-steps), begin each line with 1.
You don’t need to specify the numbering. Markdown does that for you.
Adding blank lines before and after each step is optional. To create sub-steps, indent the next lines.
Syntax
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.
For more syntax help, see Numbered lists and bullet lists.
Content types in a task
Task (or procedure / exercise) 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 tasks
Use sentence style capitalization for 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)
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 is about marking text, cells, and similar items that are subject to a user action (such as copying text), and also about picking options from a list.
-
Click: Click is about mouse actions. “Click Find.” Note the following best practices for click:
- Avoid calling out the control type (“Click the Find 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.)
See Describing Actions in the UI in the Microsoft® Manual of Style for guidance.
Complex procedures complex-step
Complex procedures might include a concept, step-heading, multiple steps with sub-steps, or bullets with field descriptions. For multiple-step procedures in numbered lists:
-
If a procedure contains lengthy sub-steps (or sub-tasks), you might need to re-think your presentation. Perform a task analysis and break up the procedure into two smaller tasks if necessary.
-
When adding conceptual information before the steps, consider using a brief step heading (a “To” heading) to orient readers to the task. The step heading should mirror its preceding heading:
- Example H1: Configure processing options
- Example step-heading: To configure processing options
-
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, brief, clear commands.
-
Use consistent sentence structures. For example, always use similar prepositional phrases when orienting the reader. The rest of the time, begin each sentence with a verb. (Goal before action.)
Examples:
- On the Calendar panel, select Today.
- To specify a date, select Calendar.
- For Alignment, choose Left.
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:
