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 of | Try |
|---|---|
| has a requirement | needs |
| however | but |
| identical | same |
Avoid#
- Using acronyms unless the acronym is well known.
- Using jargon.
- Using idioms and phrases with indirect or ironic meanings.
- Unnecessary or repeated words
Sentence vs title case#
You should always write in sentence case.
- It is easier to read.
- It is easier to be consistent about what gets capitalized vs what does not.
- It is easier for the reader to identify proper noun's, which should always be capitalized.
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.
| Active | Passive |
|---|---|
| Customer deleted | The customer was deleted |
| Name required | The 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.
| Do | Do not |
|---|---|
| Create purchase order | Create 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 and clear language.
- Keep headings to a single sentence.
- Avoid using punctuation.
- Write in sentence case.
| Do | Do not |
|---|---|
| Purchase orders | Purchase 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".
| Do | Do 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.
| Do | Do not |
|---|---|
| Saturday, October 17 2020 | Thur, October 17 |
| October 17, 2020 | October 17,'20 |
| Oct 17, 2020 | 10/17/20 |
| Oct 17 | Oct 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.
| Do | Do not |
|---|---|
| \$1,000.00 USD | USD \$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
| Do | Do not |
|---|---|
| \$1000.00 USD | USD \$1000.00 |
| \$1000.00USD | |
| \$1,00...USD |
Country, Province and State names#
- Use a nations proper name when referring to is as a noun.
| Do | Do not |
|---|---|
| United States | US |
- When using a country as an adjective use the abbreviated form without punctuation.
| Do | Do not |
|---|---|
| US Currency | U.S. Currency |
Punctuation#
Ampersands#
Dont use ampersands (&). Spell out the word "and".
| Do | Do not |
|---|---|
| Shipping and receiving | Shipping & 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')
| Do | Do not |
|---|---|
| Retailer's store | Retailers store |
| Men's clothing | Mens clothing |
| Customers' credit cards | Customers 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.
| Do | Do 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.
| Do | Do not |
|---|---|
| Re-order | Reorder |
| Resend | Re-send |
Periods#
In general, only use periods in interface copy if it is a full sentence description.
| Do | Do not |
|---|---|
| Complete sentences | Sentence fragments |
| Body text, descriptions and subtitles | Top-level headings and titles |
| Help text under inputs | Buttons 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.
| Do | Do not |
|---|---|
| Color | Colour |
| Center | Centre |
| Canceled | Cancelled |
Bold#
Use bold sparingly and only where strong emphasis is required.
Italics#
Avoid italics as it can cause Accessibility challenges.