Skip to main content
All CollectionsInternal
Help Center writing standards
Help Center writing standards

Learn the writing standards for Help Center articles so you can contribute content consistent with the rest of the articles.

Chris Ramlow avatar
Written by Chris Ramlow
Updated over a week ago

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.

*even though it is in all caps in the UI

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.

  1. Open the profile menu and select Add Event.
    The New Event page opens.
    [IMAGE OF NEW EVENT PAGE HERE]

  2. Enter a Title for the event.

YES

  1. Open the profile menu and select Add Event.
    The New Event page opens.

  2. Enter a Title for the event.
    [IMAGE OF THE NEW EVENT PAGE HERE]

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

  1. Open the profile menu and select Dashboard.
    The Dashboard opens.

  2. Select Surveys on the left side of the page.

  1. Open the profile menu and select Dashboard.

  2. The Dashboard opens.

  3. Select Surveys on the left side of the page.

  • Open the profile menu.

  • Select Dashboard.

  • The Dashboard opens.

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.
[END OF PROCESS]

YES

2. Select Edit for the event.

3. Edit the Title for the event.
[END OF PROCESS]

NO

Bulleted lists should be parallel.

  • Field Name 1: it does this

  • Field Name 2: it does that

YES

  • Field Name 1: it does this

  • Field Name 2: click this field to do that

NO

Did this answer your question?