When writing or editing Help Center articles, use the following standards as guidelines.
Formatting, grammar, and word choice
Generally, our voice and style should not talk down to users, but should feel as though we are speaking to a respected colleague.
Put names of fields, buttons, and so on, in bold text.
Click Start. | YES |
Click "Start". | NO |
Click Start. | NO |
Don't refer to UI elements if possible (like button, field, and so on).
Click Save. | YES |
Click the Save button. | NO |
Don’t capitalize items in the UI unless referring to actual fields, buttons, and so on.
To create an event: | YES |
To create an Event: | NO |
Select Add Event. | YES |
Events module | YES |
Events Module | NO |
Use second person when referring to the reader.
You can schedule an event based on an event type. | YES |
The user can schedule an event based on an event type. | NO |
Use present tense verbs, avoiding "will" or "would then."
The menu opens when you click the button. | YES |
The menu will open when you click the button. | NO |
When you click the button, the menu would then open. | NO |
Avoid pleasantries (if desired, please, simply, and so on).
Optionally, re-order the track steps. | YES |
If desired, re-order the track steps. | NO |
Simply re-order the track steps. | NO |
Don’t use Latin abbreviations.
Do not use | Do use |
etc. | and so on |
e.g. | for example |
Use sentence case for article titles and headings and title case for UI fields and buttons.
| YES | NO |
Article titles | Help Center writing standards | Help Center Writing Standards |
Article headings | Go deeper | Go Deeper |
UI elements | Select Add Event from the menu. | Select ADD EVENT from the menu. |
Avoid referring to the "system" or "application" when talking about the instance of PlusPlus the reader is using. If it can't be helped, use "system."
A confirmation dialog appears. | YES |
The system displays a confirmation dialog. | NO |
You select from a list of options and click on a button that takes action.
Select Dashboard from the menu. |
Click Bulk Import. |
Buttons are clickable, and icons are not, so don’t tell users to click an icon. When buttons are images (like a context menu), describe what the button looks like in parentheses.
Open the context menu (button with three dots). | YES |
Click the three dot icon to open the context menu. | NO |
Images
Be as sparing as possible with images since they are difficult to maintain long-term. Use screenshots only when they are needed to clarify the instructions given.
When possible, place images above the text that references it.
This helps convey a logical flow from step to step where an image shows the result of an action taken. For example, if you direct readers to click a button to open a new page, an image of that page should appear after the “click button” step and before the instructions of what to do on that page.
|
YES |
|
NO |
Step-by-step instructions and lists
List procedure steps as numbers, not bullet points. If you need to note the result of a step, put it after a line break within the step rather than delineating it as another step. Steps are actions the user takes, not the result of the action.
YES | NO |
|
|
|
|
Combine two steps when the second logically completes the first and it reasonably reduces the number of steps in the process.
3. Open the menu and select Add Event. | YES |
3. Open the menu. 4. Select Add Event. | NO |
Always include the concluding step of a process, such as: Save your changes.
2. Select Edit for the event. 3. Edit the Title for the event. 4. Save the event. |
YES |
2. Select Edit for the event. 3. Edit the Title for the event. |
NO |
Bulleted lists should be parallel.
|
YES |
|
NO |