Terminology and Wording

I took this from, Hi’s styleguide as I don’t trust anyone to keep anything online. So this is just a local copy with opinions about word choices.

Note: Consider consulting with a technical writer before you commit UI text. Tech writers can help with clarity and consistency of UI text.

Avoid Using “Please”

Using “please” is unnecessary, unless you are asking the user to do something that is inconvenient or a result of a system error.

DoDo not
Select custom applicationPlease Select a custom application
Error encountered while executing the selected rules. Please contact system administrator for further assistanceError encountered while executing the selected rules. Contact system administrator for further assistance

Avoid Using Words Interchangeably

Some words can have multiple meanings, depending on the context. Often, these words are used interchangeably with another word. For clarity, select and consistently use the less ambiguous meaning for each word.

For example, because and since should not be used interchangeably. The word since can have two meanings. To avoid ambiguity, always use because to provide a reason, and use since when referring to a specific point in time.

DoDo not
Group approval for {0} was deleted because it no longer matches approval rule {1}Group approval for {0} was deleted since it no longer matches approval rule {1}

As another example, once and _after_should not be used interchangeably. The word once has two meanings. Always use after when referring to events that occur later than or in succession to another event, and use once when referring to events that occur one time.

DoDo not
You cannot change the State after it is Closed or CanceledYou cannot change the State once it is Closed or Canceled

Spell Out Contractions

Contractions can be hard to translate. Avoid contractions if at all possible.

DoDo not
You do not have any archived tasksYou don’t have any archived tasks

Use Present Tense

Present tense is easier to read and understand.

Avoid future tense and past tense if at all possible.

DoDo not
Problem is closed when the related change is marked Closed CompleteProblem will be closed when the related change is marked Closed Complete

Write Brief But Effective Text

In messages that tell users about an action that they can perform, use active voice by providing a direct command or addressing users directly with you.

DoDo not
Specify the start dateStart date must be specified
You can create bookmarks by dragging a link to the left edgeBookmarks are created by dragging a link to the left edge

Only include enough detail to help users complete tasks.

DoDo not
Provide a brief explanation for rejecting this codeEnter your comments for rejecting this code. This comment will be useful for the developer who submitted this code change
Edit the report settings, and then click Run ReportYou’ve chosen Edit mode, make adjustments above and press the button titled Run Report

Remove unnecessary words. Examples of words that you can usually remove without altering your meaning include: - Adverbs. For example, really, quickly, and easily. - Articles (for example, the, a, and an) in the beginning of sentences. - Forms of “to be” that are used with another verb.

DoDo not
Article was not foundUnfortunately, the article cannot be found
Chart is loadingThe chart is being loaded

Edit this page

Avatar
Jace Benson
ServiceNow Developer

ServiceNow is my day job, JAMStack is my passion.