Adhering to certain rules of grammar and mechanics helps us keep our writing clear and consistent. This section will lay out our house style, which applies to all of our content unless otherwise noted in this guide. (We cover a lot of ground in this section—the search feature will help if you're looking for something in particular.)
Basics
Write for all readers. Some people will read every word you write. Others will just skim. Help everyone read better by grouping related ideas together and using descriptive headers and subheaders.
Focus your message. Create a hierarchy of information. Lead with the main point or the most important content, in sentences, paragraphs, sections, and pages.
Be concise. Use short words and sentences. Avoid unnecessary modifiers.
Be specific. Avoid vague language. Cut the fluff.
Be consistent. Stick to the copy patterns and style points outlined in this guide.
Guidelines
Abbreviations and acronyms
If there’s a chance your reader won’t recognize an abbreviation or acronym, spell it out the first time you mention it. Then use the short version for all other references. If the abbreviation isn’t clearly related to the full version, specify in parentheses.
- First use: Network Operations Center
- Second use: NOC
- First use: Coordinated Universal Time (UTC)
- Second use: UTC
If the abbreviation or acronym is well known, like API or HTML, use it instead (and don’t worry about spelling it out).
Active voice
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.
- Yes: Marti logged into the account.
- No: The account was logged into by Marti.
Words like “was” and “by” may indicate that you’re writing in passive voice. Scan for these words and rework sentences where they appear.
One exception is when you want to specifically emphasize the action over the subject. In some cases, this is fine.
- Your account was flagged by our Abuse team.
Capitalization
We use a few different forms of capitalization. Title case capitalizes the first letter of every word except articles, prepositions, and conjunctions. Sentence case capitalizes the first letter of the first word.
When writing out an email address or website URL, use all lowercase.
- freddie@mailchimp.com
- mailchimp.com
Don't capitalize random words in the middle of sentences. Here are some words that we never capitalize in a sentence. For more, see the Word List.
- website
- internet
- online
Contractions
They’re great! They give your writing an informal, friendly tone.
Emoji
Emoji are a fun way to add humor and visual interest to your writing, but use them infrequently and deliberately.
Numbers
Spell out a number when it begins a sentence. Otherwise, use the numeral. This includes ordinals.
- Ten new employees started on Monday, and 12 start next week.
- I ate 3 donuts at Coffee Hour.
- Meg won 1st place in last year’s Walktober contest.
- We hosted a group of 8th graders who are learning to code.
Sometimes it feels weird to use the numeral. If it's an expression that typically uses spelled-out numbers, leave them that way.
- A friendly welcome email can help you make a great first impression.
- That is a third-party integration.
- Put your best foot forward with the all-in-one Marketing Platform that grows with you.
- After you send your newsletter, Freddie will give you a high-five.
Numbers over 3 digits get commas:
- 999
- 1,000
- 150,000
Write out big numbers in full. Abbreviate them if there are space restraints, as in a tweet or a chart: 1k, 150k.