Grammar and Mechanics

This guide is to help designers, UX designers, marketers, sales, support, developers, recruiters, and product managers — anyone who writes public-facing text for Commure.

Basics

Active voice

You should (almost) always write in the active voice:

  • Subject (person/thing acting) verb (the action) object (receives the action)

Use the active voice if physician need to do something. It should be clear that the subject is the one doing the action.

Add details to the patient diagnosis.
Details were added to the patient diagnosis.

Passive voice

To tell if you’re using the passive voice, look out for:

  • When the object comes before the subject (“the item was purchased by the customer”)
  • Past tense verbs (“was added”, “was created”, and so on)
  • Forms of the verb “to be” (“was”, “is”, “were”, and so on)

You should generally write in the active voice, but here’s when to use the passive voice:

  • To avoid referring to yourself or Commure
  • To make it clear that you didn’t personally take an action or make a decision
  • If the object (thing being done) is more important than the subject (person doing the thing)
Reports are created monthly and emailed to the chiefs and attending physicians.
Commure creates and emails your reports monthly to chiefs and attendings.

Contractions

Contractions are abbreviated words. We use them to set a light and casual tone in the interface. The goal is to sound human, so avoid contracting verbs that sound awkward when you say them out loud, or that have been phased out of modern speech. One last note, keep the tone professional - some contractions are better used when texting friends or trolling twitter, and are not suitable in a business context.

You can’t have ....
That’ll make sure you are all set up
... products don’t have ...
It would’ve been possible if you’d downloaded the latest update
You’re all set ...
The set up was not complete, but this will do
... doesn’t require ...
You gotta set up Commure SSO to use Commure Listrunner

Plain language

Use words and language that our physician use. Avoid jargon or technical terminology. Make sure each sentence has a single focus and keep them short. Aim for a Grade 7 reading level, but do keep in mind that physicians are highly educated.

To a physician: We’ve made some changes to improve your app’s security
To a physician: Your SSL certificates were activated
Please log in using your hospital-provided user name and password
Use your hospital's SSO credentials to log in

Capitalization

Headings

Use sentence case for all headings:

  • Capitalize the first word of a heading
  • Capitalize proper or trademarked nouns (names of companies/products, countries, or people)
  • Lowercase for everything else
Create prescriptions
Create Prescriptions

Product and feature names

In general, if a feature or product isn’t unique to Commure, don’t capitalize it (such as blogs, navigation, pages). If it’s unique to Commure and marketable as its own product, capitalize it (such as Commure Listrunner, or Commure Notes).

For all terms and definitions, check our full vocabulary list.

developer platform
Developer Platform
navigation
Navigation
Commure Listrunner
commure listrunner

Job titles

Job titles should be capitalized when they come before or after a person’s name. When referring to a job title without directly referencing a name, don’t capitalize the job title.

Content Strategist Jon Doe
content strategist Jon Doe
Jon Doe, Content Strategist
Jon Doe, content strategist
Jon Doe is a content strategist.
Jon Doe is a Content Strategist.
The content strategist designed the information architecture.
The Content Strategist redesigned the information architecture.

Letters following slashes

The first letter following a slash shouldn’t be capitalized.

Zip/postal code required
Zip/Postal code required

Headings and subheadings

See the content guidelines for headings and subheadings in the actionable language section.

Lists

Bulleted

Use a bulleted list when items are related but sequence or priority doesn’t matter.

Use Commure Listrunner to:

  • Customize your apps to work the way you need for any given task
  • Automatically pull relevant patient information directly from your EMR
  • Easily manage access rights to your lists using Commure admin

Use Commure Listrunner to:

  • Customize your apps to work the way you need for any given task
  • Automatically pull relevant patient information directly from your EMR
  • Easily manage access rights to your lists using Commure admin

Numbered

Use a numbered list when item sequence or priority does matter, such as step-by-step instructions.

To set up Commure Listrunner:

  1. Go to Settings from Commure admin
  2. Select Commure Listrunner
  3. Select Setup

To set up Commure Listrunner:

  • Go to Settings from Commure admin
  • Then select Commure Listrunner
  • After that select setup to activate the account

Dropdown menus

Actions in a menu

Menu lists give users a horizontal set of actions when space is limited. The order of actions is often based on logic, such as most popular actions first.

Actions in a menu follow a {verb}+{noun} pattern. If there’s enough context, only a verb might be required.

Edit
editing options
Rename

change the name

Duplicate
Duplicate this order so that you can make edits, updates, or changes
Delete
delete

Nouns in a menu

Menu lists give users a horizontal set of nouns when space is limited. The order of nouns is often based on logic such as most recent orders.

Nouns in a menu should be concise but still give the user enough information so they can easily find and accurately select the item they want.

Select filter

Today
Filter visibility
Yesterday
Filter product type
This week
Filter product vendor
This month
Filter tagged with

Capitalization

  • List items always start with a capital letter.
  • Capitalization and punctuation rules apply to both bulleted and numbered lists.

Patient name

  • Hidden
  • Optional
  • Required

Patient name

  • hidden
  • optional
  • required

Punctuation

  • Introduce bulleted lists with a colon or a heading.
  • Don’t put a comma or semicolon at the end of a bulleted or numbered list item. Treat each list item as a self-contained piece of information.
  • If any list item contains two or more sentences, punctuate all list items.
  • If all list items are one sentence or fragments, don’t punctuate. If necessary, use a comma for readability.

How to punctuate lists:

  • Don't punctuate if everything in the list is short or a fragment
  • If needed, then a comma can be used
  • A comma can be used but a rewrite is a good alternative

Without a colon, it's not always clear when a list starts

  • unneeded punctuation adds visual clutter.
  • Most people think it odd to end a line with a semicolon;
  • Complete sentences in a list require full punctuation. In this case, you need to ensure a consistent style

Helper text and descriptions

If your list contains helper text, only the description below the list item should contain punctuation.

To gain access to your team's patient lists:

  • Log into the Commure portal using your hospital-provided username and password If this is your first time trying to log in, it will not be successful. This is normal! You will receive an email with these same instructions. If you've already gotten access, skip to step 4.
  • Contact your chief and ask them to use Commure admin to grant your account access Only a few people on the team have administrative rights. Ask your colleagues if you're not sure who to talk to.
  • Log into the Commure portal and select Listrunner Listrunner is the tool your team is using to manage their lists. If you need a quick overview, ask a colleague. If you run into any technical problems, then contact csupport@commure.com with the details.

To gain access to your team's patient lists:

  • Log into the Commure portal using your hospital-provided username and password If this is your first time trying to log in it will not be successful This is normal
  • Contact your chief and ask them to use Commure admin to grant your account access. Ask your colleagues if you're not sure who to talk to
  • Log into the Commure portal and select Listrunner ask a colleague for help if you need it

Dates, numbers, and addresses

These guidelines are for American English, which is the language we use as a base. However, dates, numbers, and addresses may be formatted differently depending on region or team preferences.

Date

When possible, use the full name for days and months, for example, October. If there are space constraints, use 3-letter abbreviations, for example, Mon or Oct. Don’t write dates numerically, for example, 07-02-14. Use an en dash without a space on either side for date ranges.

Thursday, October 15, 2020
Thur, October 20
October 15, 2020
October 15, 20
Oct 15, 2020
10/15/20
Oct 15-Nov 15
Oct 15 - Nov 15

Don’t use ordinal indicators, which are words representing position or rank in a sequential order (1st, 2nd, 3rd, and so on).

January 23–April 1
January 23rd–April 1st

Time:

  • Use the 12-hour clock, followed by am or pm.
  • Include a space after the last number, for example, “Your patient will arrive at 12:35 pm”. Among other reasons, adding the space helps with formatting.
  • Use the browser time of the logged in user.
  • To show a time range, use an en dash without spaces and include the am/pm after both times, for example, 3:00 pm–4:00 pm.
  • If indicating both the date and time, separate them with the word “at”, rather than with a comma.

Time zones

  • Include a time zone only if it’s necessary, such as for an event listing.
  • Use the time zone’s abbreviation following the am or pm, for example, 4:00 pm ET.
  • If your audience is in a single time zone, then don’t include an S (for Standard) or D (for Daylight). For example, 3:00 pm PT.
  • If your audience is in a combination of time zones, then include the S (for Standard) or D (for Daylight) to avoid confusion. For example, 3:00 pm PDT.
Thursday, October 15, 2020 at 2:00 pm EDT
2015-10-20, CDT 2:00P.M.

Use consistent timestamp formats by following these examples:

Less than 1 min: Just now
Less than 1 min: 10:30am
1 min to 60 min: 13 minutes ago
1 min to 60 min: 10:30am
Today: 10:30 am
Today: Today, 10:30am
Yesterday: Yesterday at 10:30 am
Yesterday: Friday, 10:30am
In the last 7 days: Friday at 10:30 am
In the last 7 days: Friday, 10:30am
7 days to 1 year: Aug 14 at 10:30 am
7 days to 1 year: 10:30am, Oct 15, 2020
More than 1 year: Aug 14, 2021
More than 1 year: Last year

Currency

When including currency with a price, the currency comes after the dollar amount with a space to separate them.

$10,000 USD
$10KUSD
USD$10,000
$10,000USD

Numbers

In general, use numerals. If the number is below 10 and not integral to the sentence, spell it out in full.

9
nine
100
one hundred
1
one
Here are 2 marketing campaigns you can use.
Here are two marketing campaigns you can use.
You have 3 orders to fulfill.
You have three orders to fulfill.
You no longer need to track shipments in two places.
You no longer need to track shipments in 2 places.

Use commas for numbers with four or more digits. Place commas after every third digit from right to left. Whenever possible, don’t truncate numbers:

12,000
12 k
9,344
9344
1,800,887
1.8 m

Use hyphens when writing phone numbers. Don’t use brackets, spaces, periods, or plus signs:

415-555-1234
415.555.1234
1-510-555-1234
1-(510)-555-1234
49-55-555-123
+49 55 555 123

Use an en dash without a space on either side for number ranges:

5–10 products
5 – 10 products
2005–2015
2005 – 2015

Use “to” instead of an en dash if a number range is preceded by “from” in a phrase. Use “and” if a range is preceded by “between”.

You have a delivery scheduled from 10:00 am to 2:00 pm on Monday, July 18.
You have a delivery scheduled from 10:00 am–2:00 pm on Monday, July 18.
Active from August 15 to August 30

For undefined upward ranges, use “and up” or “or more”.

$50.00 and up 100 or more

$50.00+

$50.00

For downward ranges, be specific.

$0.00–$49.99

$50.00 or less <$10K USD

Units of measurement

For storage and memory sizes, the unit of measurement should be uppercase. Include a space between the number and unit of measurement.

512 KB
2kb
1 GB
1000Mb
1 TB
1tb

For dimensions and weights, the unit of measurement should be lowercase. Include a space between the number and unit of measurement.

4 lbs
4 LBS
72 dpi
72DPI
500 × 500 px
500 by 500PX

For dimensions and weights, use decimals instead of fractions:

2.375 lbs
2-3/8 lbs
11.875 × 3.375 × 13.625 cm
11-7/8 × 3-3/8 × 13-5/8 cm'

When listing out dimensions in a row, put the unit of measurement at the end instead of after each number and include a space.

11.875 × 3.375 × 13.625 cm
1.875cm × 3.375cm × 13.625cm

In all cases, include a space between the number and the unit.

3.4 lbs
3.4lbs
2 kg
2kg
1.875 × 3.375 × 13.625 cm
1.875 × 3.375 × 13.625cm

Address

Lay out address forms in the following format:

First name Last name Address Apartment, suite, etc. (optional) City Country Province Postal code

Please note, “optional” in Apartment, suite, etc. (optional) means that the field is optional for customers to complete, but we should always provide the option in address forms.

Places, names, and formal nouns

Country, province, and state names

Use a nation’s proper name when referring to it as a noun.

Your hospital must be located in the United States.
Your hospital must be located in the US.

When using a country as an adjective (such as when referring to currency), use the abbreviated form without punctuation.

The insurance company requires your hospital to use US currency.
U.S. currency

Things to watch out for:

  • Don’t use colloquial forms of a nation or state name, for example, America instead of the United States
  • Search online to see whether nations commonly use “the” before their name, for example, the Philippines or the Falkland Islands

Trademarks

Respect the usage guidelines of any third-party intellectual property. For example, in US communications, Apple Pay(™) requires you to include the trademark symbol (™) the first time Apple Pay appears in body copy.

Review the third party’s brand usage guidelines to make sure you are using the company’s name and logo correctly.

Punctuation

Ampersands

Don’t use ampersands (&). They attract attention to the least important part of the sentence. Spell out the word “and”.

Zones and rates
Zones & rates

Apostrophes

Use apostrophes to represent omitted letters or numbers:

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

Use apostrophes to form possessives:

  • Singular nouns: add ’s, even if they end in s (merchant’s, bus’s)
  • Plural nouns that don’t end in s: add ’s (women’s, men’s)
  • Plural nouns that end in s: add an apostrophe (boxes’, customers’)

Don’t use apostrophes to form possessive pronouns such as hers or his.

The physician's schedules
The physicians' schedules
Patient’s heart rate
Patients' heart rates

Always use apostrophes, not vertical (straight) quotes.

Colons

Avoid using colons in sentences. If you need to use one, don’t capitalize the first word after the colon unless it’s a proper noun.

Your hospital can accept payments with credit cards and Apple Payments. (avoid but acceptable:) Your hospital can accept payments with: credit cards and Apple Payments.
Your hospital can accept payments with: Credit cards and Apple Payments.

Don’t use colons to introduce radio buttons or checkboxes.

Send an email reminder about their appointment CHECKBOXES LIST HERE

Send an email reminder about their appointment: CHECKBOXES LIST HERE

Introduce bulleted lists with a colon.

Correct the following patient information to continue: BULLETED LIST HERE

Correct the following patient information to continue. BULLETED LIST HERE

Commas

Use the oxford comma (also known as the serial comma) in sentences. There should be a comma after every list of 3 or more items (unless you’re using a bulleted or numbered list).

Listrunner is an app that handles your topic 1, topic 2, and topic 3
Listrunner is an app that handles your topic 1, topic 2 and topic 3

Don’t use commas to separate bulleted or numbered list items.

Ellipses

The ellipses (…) can be used in place of a missing piece of text (most commonly to show the deletion of words from a direct quotation). Avoid using ellipses in text.

Use ellipses for:

  • Truncation in the center of a title bar

Don’t use ellipses for:

  • Placeholder copy
  • Trailing off a sentence
Search files
Start typing to search for files…

Always use the ellipsis character, not three periods.

Truncation

Consider constraints of the space in the interface when deciding to use truncation. Think about what part of the string physicians needs most. It’s usually the beginning or end, which means you might have to truncate the middle of the string.

Ellipses button component

A button with an ellipsis icon (not the same as text) is used to expand more actions. It’s typically used in cards, or for horizontal sets of actions when space is limited. Android uses a vertical version (vertically stacked dots).

En-dashes and em-dashes

Use an en dash with no spaces in between (–) for a fixed range of numbers, for example 2006–2013.

Use an em dash only if you can’t make your message clearer by splitting it into two sentences. Use an em dash without a space on either side (—). Do not do this mid-sentence.

Do

Review your patient cases, outstanding tasks, and next steps—all in one place.

Don’t

Review your patient cases-updates, outstanding tasks, and next steps—all in one place.

Depending on the font or appearance, you may want to include a hair space on either side of the en or em dash. HTML entity code for hair space is &hairsp; or &#8202;.

Exclamation marks

Avoid exclamation marks—only use them for really really exciting things. If you absolutely have to, limit yourself to one exclamation mark per page.

You’ve just added your first patient!
You’ve updated your patient's diagnosis!

Hyphens

Use hyphens to:

Form compound modifiers: two words that combine to modify or describe the noun that follows.

This is a high-risk order. This order is high risk. Add weight-based medications. Add medications prescribed based on the patient's weight.
This is a high risk order. This order is high-risk. Add weight based medications. Add medications prescribed based on patient-weight.

Join prefixes and suffixes only if there are two vowels beside each other - check if the resulting word already exists (e.g. reassign). Never use hyphens in the words e-commerce and email.

Re-order Reassign Resend
Re-enable Re-assign Re-send

Periods

Periods often end up in places they shouldn’t, and are omitted at strange times. In general, don’t use periods in interface copy unless it’s a full sentence description.

When to use periods:

  • Complete sentences
  • Body text, descriptions, and subtitles
  • Help text under text boxes (such as form fields)
  • Timeline events

When to leave out the periods:

  • Sentence fragments
  • Top-level headings and titles
  • Buttons
  • Notifications
  • Toast messages
  • Placeholder copy
  • Navigation menu items
  • Hover/tooltip text
  • Footer help box text
  • Radio button and checkbox text
  • Description example: Add this patient to a list so they're easy to find.
  • Placeholder example: Search patients
  • Timeline example: A new patient was added to the list.
  • Footer help box example: Learn more about components
  • Button example: Add patient.

  • Placeholder example: Search…

  • Heading example: Patient list, only your patients.

  • Notification example: 6 patients have been added to your list.

Periods for bulleted, numbered, and lists of links

  • Use when a list item has two or more full sentences, then also add periods to each other item in the list

  • Use for the description or helper text below a bulleted or numbered list item

  • Don’t use periods when a list has only single sentences or fragments

  • Don’t use periods for lists of links

Question marks

Avoid question marks wherever possible. Reword into affirmative statements wherever you can, but there are exceptions:

It’s okay to use question marks if you don’t know the result of the question:

  • “Did you forget your password?”
  • “Do you need to add insurance information?”

Don’t use question marks if:

  • It’s the only option available: “Reset password”
  • It’s an on/off option: “Show quantity box”

Quotation marks

Use quotation marks to:

  • Define words (“growth-hacking”)
  • Quote text

Place commas and periods inside quotation marks.

“I see this all the time,” said Mark Hayes.
“It drives me absolutely crazy”, said Mark Hayes.

Always use smart (curly) quotes, not vertical (straight) quotes.

  • "
  • '

Semicolons

Avoid semicolons when possible. If you really need them, use semicolons to:

  • Connect two closely related ideas, as long as they are both independent clauses; effectively full sentences that could almost stand on their own.
  • Replace a comma or the word “and” between two closely related ideas.

Do

My friends made me banana pancakes on my birthday; I’ve never been happier.

Better still

My friends made me banana pancakes on my birthday and I’ve never been happier. My friends made me banana pancakes on my birthday. I’ve never been happier.

Don’t

The unicorn was hungry; the grass was brown.

Spelling and formatting

American spelling

Use American spelling for all external-facing Commure content. When in doubt, check the Merriam-Webster dictionary for the preferred spelling of specific terms.

  • Color
  • Center
  • Canceled
  • Colour
  • Centre
  • Cancelled

Tip: it’s easy to miss Canadian spelling, eh. Switch your laptop language settings to American English and turn spell check on. It will highlight any Canadianisms you might have missed.

Bold

When in doubt, don’t bold.

Use bold sparingly and only where strong emphasis is required. In the interface, bold should be reserved to emphasize input that physicians have provided (such as a list names or group names).

Don’t use bold to emphasize proper nouns, create a heading, or emphasize a checkbox title.

Do

After submitting the help form, Listrunner support will email you at provider@email.com with instructions.

Don’t

Are you sure you want to delete that?

You, we, and other personal pronouns

Addressing physician

Always refer to a physician as “you”. Don’t put words in a physician’s mouth with phrases that use “I” or “my”.

Change your email address in your Profile.
Change my email address in My Profile.

In some cases (such as getting legal consent or granting permissions) you should refer to physician as “I”.

I agree to the terms and conditions
You agree the terms and conditions