Grammar and Mechanics

Plain language#

Writing using plain language means the language is straightforward and communicates concepts as efficiently as possible. As a benchmark, we consider plain language to be a United States grade 7 reading level. Grade reading level can be checked using apps like hemmingwayapp.

Do#

  • Readers should understand the message quickly, without having to decipher complicated sentences or vague jargon.
  • Always choose a short, simple word over a long and complicated one.
  • If using an acronym include a spelled out version for the first occurrence it is used on the page.
Instead ofTry
has a requirementneeds
howeverbut
identicalsame

Avoid#

  • Using acronyms unless the acronym is well known.
  • Using jargon.
  • Using idioms and phrases with indirect or ironic meanings.
  • Unnecessary or repeated words

Active versus passive#

You should almost always write in the active voice, meaning that a sentence has a subject that acts upon the verb. Sentences in the active voice have a strong, direct, and clear tone. Avoid using a passive voice, meaning the subject is the recipient of a verb’s action. In rare cases where the passive voice sounds more natural than the active voice, use passive voice.

ActivePassive
Customer deletedThe customer was deleted
Name requiredThe form needs the name to be added
Delete customer?Are you sure the customer should be deleted?

Encourage action#

People use our software to get things done, whether they’re managing a store, or making a purchase. Content should be written and structured to help the user take the most important actions.

Do#

  • Start 'calls to action' with a strong verb that describes the action a person will take when they click.
  • Use the active voice to clarify the subject and the action.
  • Prioritize the most important information and task - do not make people dig to find what they care about.

Avoid#

  • Apologies, ambiguity, or questions such as "Warning!" or "Are you sure?" because they introduce extra visual clutter.

Be consistent#

To help users understand key concepts and actions they can take, use consistent nouns (words used to identify people, places, or things) and verbs (action words) wherever possible. See Actionable Words.

Do#

Make a list of all nouns and verbs in the experience you are building.

  • Does each word clearly describe the object or action it represents in the simplest way possible?
  • Does your langauge reflect how people think?
  • Are there synonyms? Eliminate them. Each important object or action should have a single word to represent it.
  • Does your language match what is used in other experiences across the solution?

Capitalization#

  • Use sentence case for all headings.
  • Capitalize the first word of a heading.
  • Capitalize proper nouns (names of products, countries, or people.)
  • Capitalize product names. (Queue, Pay Anywhere, Payments etc.)
  • Lowercase for everything else.
DoDo not
Create purchase orderCreate Purchase Order
CREATE PURCHASE ORDER

Headings#

Headings and subheadings are labels that refer to sections of the interface.

  • Be informative and descriptive.
  • Help users understand what they will find in the section below.
  • Use simple, clear language.
  • Keep headings to a single sentence.
  • Avoid using punctuation.
  • Write in sentence case.
DoDo not
Purchase ordersPurchase Orders
Purchase orders.
Manage purchase orders!

Sentences#

  • Start sentences with imperative verbs (gives an order or command). Users should feel like they are being instructed what to do.
  • Avoid using permissive langauge like "you can".
DoDo not
Select a supplier and location to choose products.You can add products by selecting a supplier and location.

Buttons#

See Buttoncomponent.

Lists#

  • List items always start with a capital letter.
  • Use sentence case.
  • Always use the {verb} +{noun} format unless the action is clear with a single verb.
  • Introduce with a colon or a heading.
  • If any list item contains two or more sentences, punctuate all list items.

Bulleted Lists#

Use when items are related but not sequence or priority does not matter.

Numbered Lists#

Use when list items are sequential or priority does matter, such as step-by-step instructions.

Dropdown#

See Dropdown component.

Dates, times, currency, numbers and addresses#

Date#

  • When possible, use the month’s full name, for example, October. If there are space constraints, use 3-letter abbreviations, for example, Oct.
  • Don’t write dates numerically.
  • Dont' use words representing position or rank in a sequential order.
  • Optional. If the use case does not require the year to be displayed it may be excluded.
DoDo not
Saturday, October 17 2020Thur, October 17
October 17, 2020October 17,'20
Oct 17, 202010/17/20
Oct 17Oct 17th 2020

Time#

  • Use the 12 hour clock with am or pm.
  • Add a space after the last number. (11:30 am). Adding the space helps with formatting for markets outside of North America.
  • Use the time of the logged in user.
  • To show a time range, use an en dash and include the am/pm after both times. (3:00 pm-4:00 pm)
  • If listing data and time, separate them with the word "at" rather than with a comma. (Thursday, October 17 2020 at 5:00 pm.)

Currency#

  • When including currency with a price the currency comes after the dollar amount.
DoDo not
\$1,000.00 USDUSD \$1000.00
\$1000.00USD

Numbers#

  • In general, use numerals.
  • Use commas for numbers with 4 or more digits. (\$1,000)
  • Do not truncate numbers.
  • Use an en dash without a space on either side for number ranges
DoDo not
\$1000.00 USDUSD \$1000.00
\$1000.00USD
\$1,00...USD

Country, Province and State names#

  • Use a nations proper name when referring to is as a noun.
DoDo not
United StatesUS
  • When using a country as an adjective use the abbreviated form without punctuation.
DoDo not
US CurrencyU.S. Currency

Punctuation#

Ampersands#

Dont use ampersands (&). Spell out the word "and".

DoDo not
Shipping and receivingShipping & receiving

Apostrophes#

Use to represent omitted letters or verb contractions.

  • Omitted letters (don't, can't, won't)
  • Verb contractions (it's, you're, we're)

Use to form possessives.

  • Singular nouns: add 's (business's, retailer's)
  • Plural nouns that dont' end in s: add 's (women's, men's)
  • Plural nouns that end in s: add an apostrophe (boxes', customers')
DoDo not
Retailer's storeRetailers store
Men's clothingMens clothing
Customers' credit cardsCustomers credit cards

Colons#

  • Avoid using colons in sentences. If you need to use one, don't capitalize the first word after the colon unless it is a proper noun.
  • Avoid using colons to introduce radio buttons or checkboxes.
  • Do introduce bulleted or numbered lists with a colon.

Commas#

  • Use the oxford comma in sentences. There should be a comma after every list of 3 or more items unless you are using a bulleted or numbered list.
  • Don't use commas to separate bulleted or numbered list items.

Hyphens#

  • Use to form compound modifiers: two words that combine to modify or describe the noun that follows.
DoDo not
Start your free, no-risk, 14-day trial.Start your free, no risk, 14 day trial.
  • Use to join prefixes and suffixes only if there are two vowels beside each other. never use hyphens in the words ecommerce and email.
DoDo not
Re-orderReorder
ResendRe-send

Periods#

In general, only use periods in interface copy if it is a full sentence description.

DoDo not
Complete sentencesSentence fragments
Body text, descriptions and subtitlesTop-level headings and titles
Help text under inputsButtons or links
Notifications
Bulleted or numbered lists
Dropdown menu items
Select options
Hover / tooltip text
Radio button and checkbox text
Notifications

Question marks#

Avoid question marks whenever possible. Reword into affirmative statements wherever you can. Its ok to use question marks if you don't know the answer to the result of the question.

Quotation marks#

Use to define words or quote text.

  • Place commas and periods inside quotation marks.
  • Always use curly quotes, not vertical quotes.

Spelling and formatting#

Use American spelling for all content.

DoDo not
ColorColour
CenterCentre
CanceledCancelled

Bold#

Use bold sparingly and only where strong emphasis is required.

Italics#

Avoid italics as it can cause Accessibility challenges.

Last updated on by Diana Thomson