Copy Style Guide

1. General stylistic best practices
2. Grammar
3. Numbers
4. Error Notifications
5. Forms
6. Modals
7. Tabs/Buttons/Checkboxes
8. Links
9. References

General stylistic best practices

• Be concise. Use short words and sentences. Avoid unnecessary modifiers.
• Be specific. Avoid vague language. Cut the fluff.
• Use active voice. Avoid passive voice. In active voice, the subject of the sentence does the action. In passive voice, the subject of the sentence has the action done to it. Words like “was” and “by” may indicate that you’re writing in passive voice.
  • Yes: Marti logged into the account.
  • No: The account was logged into by Marti.
• Use positive language rather than negative language. Negative language include words like “can’t,” “don’t,” etc.
  • Yes: To get a donut, stand in line.
  • No: You can’t get a donut if you don’t stand in line.
• Don't use an article before app names.
  • Yes: Take photos with Camera."
  • No: Take photos with the Camera.
• Avoid directional instructions and any language that requires the reader to see the layout or design of the page.
  • Yes: Select from these options, (with the steps listed after the title)
  • No: Select from the options in the right sidebar.
• Avoid using “Please and Thank You”. They add unnecessary length to system notifications and may annoy.
• Avoid "you", "you're", etc.
  • Yes: The picture has been deleted.
  • No: Your picture has been deleted.
• Contractions can be used and are encouraged to provide a more human experience.

Grammar

• Leave one space between sentences, never two.
• Don’t use punctuation in a title unless the title is a question.
• Hyphens (-) are used to create a single idea out of two or more words and are always connected.
• Slashes: If it’s in a URL, use a forward slash “/”… Not a backslash “\”
• Capitalization:
  • Titles and Sub Titles/sub-headers: Should use title case.
  • Action Buttons: Should use title case.
  • List Buttons / List items: Should use title case for label; and sentence case for sub label.
  • Tabs / Filters: Should be use title case.
  • Value selector lists: Should use sentence case.
  • App names: Displayed in title case, but individual settings or modes are displayed in lower case.
  • Status Notification: Should use sentence case.
  • Header: Should use title case.
  • Body Content: Should use sentence case
• When writing a list, use the Oxford com
  • Yes: David admires his parents, Oprah, and Justin Timberlake.
  • No: David admires his parents, Oprah and Justin Timberlake.
• Avoid exclamation points.
• Periods and question marks go inside quotation marks. They go outside parentheses when the parenthetical is part of a larger sentence, and inside parentheses when the parenthetical stands alone.
• When referring generally to a file extension type, use all uppercase without a period. Add a lowercase s to make plural. GIF, PDF, HTML, JPGs
• When referring to a specific file, the filename should be lowercase: slowclap.gif, MCBenefits.pdf, ben-twitter-profile.jpg, ilovedonuts.html
• For Acronyms, use all uppercase with no periods, unless they are specifically part of a brand name or the result spells out a different word.

Numbers

• Spell out a number when it begins a sentence. Otherwise, use the numeral. This includes ordinals, too.
• Numbers over three digits get commas: 150,000
• File Size display:
  • Less than 1 KB, display <1 KB
  • 1 KB to 1,023 KB, display 357 KB
  • 1 MB to 1,047 MB, display 2.5MB (only one decimal place)
  • 1 GB+, display 3.8 GB (only one decimal place)

Error Notifications

• Concise error explanations: Try to concisely explain the situation, and explain what the user can do to resolve it.
• Never use exclamation points in failure messages or alerts.

Forms

• Form titles should clearly and quickly explain the purpose of the form.
• Use title case for form titles and sentence case for form fields.
• Keep forms as short as possible.
• Use title case for form titles and sentence case for form fields.

Tabs/Buttons/Checkboxes

• Tabs: title case capitalization and no ending punctuation. They should be limited to one or two words.
• Buttons: title case capitalization and no ending punctuation. They should always contain actions. The language should be clear and concise.
• Checkboxes: sentence case and no ending punctuation.

Links

• Navigation links should be clear and concise.
• Provide a link when referring to an external website.
• Links should look different than regular copy, strong text, or emphasis text. They should have a hover state that communicates they’re interactive, and should have a distinct active and visited state.
• When writing out an email address or website URL, use all lowercase.
• Use title case for menu names and sentence case for menu items.
• Use title case for main or global navigation. Use sentence case for subnavigation.
• Links should provide information on the associated action or destination. Avoid “click here”, “learn more, “Click for more information” or “Read this.” Instead, link relevant keywords.

Specific Words

• email: One word, lowercase, no hyphen. Never: E-Mail, Email, etc EXCEPTION: when email is used as a proper noun and is the name of an app, it can be spelled E-Mail.

Miscellaneous

• Use IANA-managed Reserved Domains in documentation and tests (example.com and example.org).
• Use RFC 5737 IP addresses in documentation and tests (192.0.2.0/24 (TEST-NET-1), 198.51.100.0/24 (TEST-NET-2), and 203.0.113.0/24 (TEST-NET-3)).

References

• Old Firefox Copy Style Guide
• [Mail Chimp Copy Style Guide] (http://styleguide.mailchimp.com/)
• Domains and IP Addresses Reserved for Documentation – and Why You Should Use Them