Copy Guidelines
I created this general UX style guide for ContentGoals using best practices for longform copy and UI writing. Every company has a different style, but this can come in handy as a basis to build on.
Punctuation
Ampersands
In general, don’t use ampersands (&). Spell out the word “and”. The only time to use an ampersand is if they are found in company names “Tiffany & Co.,” “AT&T”.
Audit Logs and Reporting
Audit Logs & Reporting
Apostrophes
Use apostrophes to represent omitted letters, numbers or verb contractions:
- 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 (user’s, lens’s)
- Plural nouns that don’t end in s: add ’s (people’s, children’s)
- Plural nouns that end in s: add an apostrophe (users’, admins’)
User’s password
Admins’ emails
Users password
Admins emails
Colons
Use these two basic rules for using colons. Use the colon after a complete sentence to introduce a list of 3 or more items.
1. Lists Within a Sentence
You must have a complete sentence in front of a colon to introduce a list within a sentence. Don’t capitalize the first word after the colon unless it’s a proper noun.
Our employees enjoy food from around the world: chilaquiles, curry, sushi, and falafel.
Our company introduced a few more integrations this week: Google, Slack, Teams, and Box.
Our employees enjoy food from around the world: Chilaquiles, curry, sushi, and falafel.
Do not use a colon in a complete sentence after phrases like “such as,” “including,” and “for example.”
Jamf is an enterprise management solution for Apple devices such as iPads, iPhones, Macs, and Apple TV.
Jamf is an enterprise management solution for Apple devices such as: iPads, iPhones, Macs, and Apple TV.
2. Bulleted Lists
Use a colon to introduce a bulleted list.
Removing a license may have failed for one of the following reasons:
- You may not be authorized
- Another license may be dependent on the one you’re trying to remove
- User or service plan may no longer exist
Removing a license may have failed for one of the following reasons.
- You may not be authorized
- Another license may be dependent on the one you’re trying to remove
- User or service plan may no longer exist
Semicolons
Avoid semicolons. Rarely will you ever need a semicolon for product copy. But if you absolutely have to, use these 2 rules:
1. Complicated commas
When writing sentences that contain complicated lists, including those where the list items themselves contain commas.
Make sure: You’re authorized to remove the license; other licenses are not dependent; the user or service plan exists; and the license is assigned by a group.
Make sure you’re authorized to remove the license, other licenses are not dependent, the user or service plan exists, and the license is assigned by a group.
2. Related sentences
The sentences should be related. The sentences should be complete and able to stand on their own. Use a semicolon to replace the word “and” or “because” between the sentences.
Keywords must be separated by a coma; they are not case sensitive.
Keywords must be separated by a coma; passwords are case sensitive.
Commas
Use the oxford comma in sentences after every list of 3 or more items (unless you’re using a bulleted or numbered list).
Check the actions you would like to run for each integration, select a trigger, and save.
Check the actions you would like to run for each integration, select a trigger and save.
Em Dashes (Sentences)
Use an em dash without a space on either side (—) to create a strong break in the structure of a sentence. Em dashes draw attention to the information suggesting it’s important.
Remove users, data, and access—all with the Offboarding Employees workflow template.
Remove users—data, and access—all with the Offboarding Employees workflow template.
En Dashes (Numbers)
En dashes are shorter than em dashes. Use an en dash with no spaces (–) for a fixed range of numbers.
April 15–April 30
April 15 – April 30
Hyphens
Use hyphens to:
1. Form compound modifiers
Compound modifiers are two words describing the noun that follows.
Start your 30-day free trial.
A cloud-based system is a hardware and software hosted by a third party.
We made a high-risk decision.
This decision is high risk.
Start your 30 day free trial.
A cloud based system is a hardware and software hosted by a third party.
We made a high risk decision.
This decision is high-risk.
2. Separate vowels in prefixes and suffixes
Use hyphens only if there are two vowels beside each other. Never use hyphens in the words onboarding, offboarding, ecommerce, and email.
Re-apply
Retry
Reapply
Re-try
Exclamation Marks
Use exclamation marks rarely—only for really really exciting things.
You’ve successfully set up your first workflow!
You’ve successfully added another user!
Periods
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 (form fields)
Timeline events
Sentence fragments
Top-level headings and titles
Buttons
Notifications
Toast messages
Placeholder copy
Navigation menu items
Hover/tooltip text
Radio button and checkbox text
Question Marks
Avoid question marks —using affirmative statements instead wherever you can. In cases where questions are necessary, use a question mark. Don’t use question marks if it’s the only option available or for on/off toggle options.
Forget your password?
Show workflow
Reset password?
Show workflow?
Quotation Marks
Use quotation marks to define words and quote text. Place commas and periods inside quotation marks.
“SaaSOps” is a term coined by BetterCloud.
“I see this often,” said David.
SaaSOps is a term coined by BetterCloud.
“I see this often”, said David.