Task steps
After the user clicks Start, a series of steps is displayed that they must perform to complete the quick start.
Follow these general guidelines when writing task steps:
-
Use "Click" for buttons and labels. Use "Select" for checkboxes, radio buttons, and drop-down menus.
-
Use "Click" by itself. Do not add "on" after it.
-
Correct example:
Click OK.
-
Incorrect example:
Click on the OK button.
-
-
Tell users how to navigate between Administrator and Developer perspectives. Even if you think a user might already be in the appropriate perspective, give them instructions on how to get there so that they are definitely where they need to be.
Examples:
Enter the Developer perspective: In the main navigation, click the dropdown menu and select Developer. Enter the Administrator perspective: In the main navigation, click the dropdown menu and select Admin.
-
Use the "Location, action" structure. Tell a user where to go before telling them what to do.
-
Correct example:
In the node.js deployment, hover over the icon.
-
Incorrect example:
Hover over the icon in the node.js deployment.
-
-
Keep your product terminology capitalization consistent.
-
If you must specify a menu type or list as a dropdown, write "dropdown” as one word without a hyphen.
-
Clearly distinguish between a user action and additional information on product functionality.
-
User action:
Change the time range of the dashboard by clicking the dropdown menu and selecting time range.
-
Additional information:
To look at data in a specific time frame, you can change the time range of the dashboard.
-
-
Avoid directional language, such as "In the upper-right corner, click the icon". Directional language becomes outdated every time UI layouts change. Also, a direction for desktop users might not be accurate for users with a different screen size. Instead, identify something using its name.
-
Correct example:
In the navigation menu, click Settings.
-
Incorrect example:
In the left-hand menu, click Settings.
-
-
Do not identify items by color alone, such as "Click the gray circle". Color identifiers are not useful for sight-limited users, especially colorblind users. Instead, identify an item using its name or copy, such as button copy.
-
Correct example:
The success message indicates a connection.
-
Incorrect example:
The message with a green icon indicates a connection.
-
-
Use the second-person point of view, you, consistently:
-
Correct example:
Set up your environment.
-
Incorrect example:
Let's set up our environment.
-