cme dev style guide logo cme dev style guide

Sticking 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.

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.

Words like “was” and “by” may signal 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.

Learn more about active versus passive voice on Grammarly.

Articles

Exceptions for A and An

Use an before consonants that sound like vowels.

Use a before vowels that sound like consonants.

This holds true with acronyms and initialisms, too: an LCD display, a UK-based company, an HR department, a URL. ~Grammarly

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.

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.

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.

Introductory phrases

This is how to write “at the time of writing”.

The comma is optional if the introductory phrase is prepositional.

Example: At the time of writing we had just released version 1.0.

If “instead” is working as a preposition, the comma is optional. Use a comma if “instead” is an adverb.

Numbers

Spell out a number when it begins a sentence. Otherwise, use the numeral. This includes ordinals.

Sometimes it feels weird to use the numeral. If it’s an expression that typically uses spelled-out numbers, leave them that way.

Numbers over 3 digits get commas:

Write out big numbers in full. Abbreviate them if there are space restraints, as in a tweet or a chart: 1k, 150k.

Dates

Generally, spell out the day of the week and the month. Abbreviate only if space is an issue in the app.

File sizes

Capitalize the abbreviation for the units. Add one space between the numbers and the units.

Image resolutions

Abbreviate pixels with a lower-case px. Add a space between the numbers and the units.

Decimals and fractions

Spell out fractions.

Use decimal points when a number can’t be easily written out as a fraction, like 1.375 or 47.2.

Percentages

Use the % symbol instead of spelling out “percent.” Avoid beginning a sentence with a percentage.

Ranges and spans

Use a hyphen (-) for a range or span of numbers. There should be no spaces before and after the hyphen in a range or span of numbers.

Money

When writing about US currency, use the dollar sign before the amount. Include a decimal and number of cents if more than 0.

When writing about other currencies, follow the same symbol-amount format:

Telephone numbers

Use dashes without spaces between numbers. Use a country code if your reader is in another country.

Temperature

Use the degree symbol and the capital F abbreviation for Fahrenheit.

Time

Use numerals and am or pm, with a space in between. Don’t use minutes for on-the-hour time.

Use a hyphen between times for a time period.

Specify time zones when writing about an event or something else people would need to schedule. For example, Mailchimp is in Atlanta, so they default to United States Eastern time.

Abbreviate time zones within the continental United States as follows:

When referring to international time zones, spell them out: Nepal Standard Time, Australian Eastern Time. If a time zone does not have a set name, use its Coordinated Universal Time (UTC) offset.

Abbreviate decades when referring to those within the past 100 years.

When referring to decades more than 100 years ago, be more specific:

Punctuation

Apostrophes

The apostrophe’s most common use is making a word possessive. If the word already ends in an s and it’s singular, you also add an ‘s. If the word ends in an s and is plural, just add an apostrophe.

Apostrophes can also be used to denote that you’ve dropped some letters from a word, usually for humor or emphasis. This is fine, but do it sparingly.

Colons

Use a colon (rather than an ellipsis, em dash, or comma) to offset a list.

You can also use a colon to join 2 related phrases. If a complete sentence follows the colon, capitalize the 1st word.

Commas

When writing a list, use the serial comma (also known as the Oxford comma).

Otherwise, use common sense. If you’re unsure, read the sentence out loud. Where you find yourself taking a breath, use a comma.

Use a comma after a coordinating conjunction that joins 2 independent clauses. Doing this is one way to fix comma splices.

Use commas before and after nonrestrictive appositive phrases.

Don’t use commas to separate restrictive appositive phrases.

Dashes and hyphens

Use a hyphen (-) without spaces on either side to link words into single phrase, or for a span or range.

Use an em dash (—) without spaces on either side to offset an aside.

Use a true em dash, not hyphens (- or –).

More on hyphens, en dashes, and em dashes

Grammarly points out for compound modifiers, “If the noun comes first, leave the hyphen out.”

Uncanny Owl warns to watch for too much hyphenation. For example, “fill in” shouldn’t be “fill-in”, unless it’s a noun and not an action.

What’s the difference between hyphens and en dashes?

The hyphen is smaller than then en dash (–). Mailchimp says above to use a hyphen for ranges. The Chicago Manual of Style (CMOS) and Grammarly say to use an en dash for ranges. Yet, outside of print, hyphens are the norm. Here’s the distinction according to CMOS.

The hyphen connects two things that are intimately related, usually words that function together as a single concept or work together as a joint modifier (e.g., tie-in, toll-free call, two-thirds). The en dash connects things that are related to each other by distance, as in the May–September issue of a magazine; it’s not a May-September issue, because June, July, and August are also ostensibly included in this range. ~CMOS

Here’s an example from Grammarly.

Grammarly says to use the word to if the word from introduces a range.

Grammarly says to use the word and if the word between introduces a range.

Ellipses

In general, avoid using ellipses.

You can use ellipses (…) to express that you’re trailing off before the end of a thought. If you need to, use ellipses sparingly and follow these rules.

Don’t use them for emphasis or drama, and don’t use them in titles or headers.

Add a space before and after an ellipsis. Don’t add a space after the ellipsis if punctuation comes after it. The following example has a period after the ellipsis.

Ellipses, in brackets, can help to show that you’re omitting words in a quote.

Periods

Periods 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.

Leave a single space between sentences.

Question marks

Question marks go inside quotation marks if they’re part of the quote. Like periods, they go outside parentheses when the parenthetical is part of a larger sentence, and inside parentheses when the parenthetical stands alone.

Exclamation points

Use exclamation points sparingly, and never more than one at a time. They’re like high-fives: A well-timed one is great, but too many can be annoying.

Exclamation points go inside quotation marks. Like periods and question marks, they go outside parentheses when the parenthetical is part of a larger sentence, and inside parentheses when the parenthetical stands alone.

Never use exclamation points in failure messages or alerts. When in doubt, avoid!

Quotation marks

Use quotes to refer to words and letters, titles of short works (like articles and poems), and direct quotations.

Periods and commas go within quotation marks. Question marks within quotes follow logic—if the question mark is part of the quotation, it goes within. If you’re asking a question that ends with a quote, it goes outside the quote.

Use single quotation marks for quotes within quotes.

Semicolons

Go easy on semicolons. They usually support long, complicated sentences that could easily be simplified. Try an em dash (—) instead, or simply start a new sentence.

Ampersands

Don’t use ampersands unless one is part of a company or brand name.

People, places, and things

File extensions

When referring generally to a file extension type, use all uppercase without a period. Add a lowercase s to make plural.

When referring to a specific file, the filename should be lowercase:

Pronouns

If your subject’s gender is unknown or irrelevant, use “they,” “them,” and “their” as a singular pronoun. Use “he/him/his” and “she/her/her” pronouns as appropriate. Don’t use “one” as a pronoun.

For more on writing about gender, see Writing about people.

Quotes

When quoting someone in a blog post or other publication, use the present tense.

Names and titles

The first time you mention a person in writing, refer to them by their first and last names. On all other mentions, refer to them by their first name.

Capitalize the names of departments and teams (but not the word “team” or “department”).

Capitalize individual job titles when referencing to a specific role. Don’t capitalize when referring to the role in general terms.

Don’t refer to someone as a “ninja,” “rockstar,” or “wizard” unless they literally are one.

Schools

The first time you mention a school, college, or university in a piece of writing, refer to it by its full official name. On all other mentions, use its more common abbreviation.

States, cities, and countries

Spell out all city and state names. Don’t abbreviate city names.

Per AP Style, all cities should be accompanied by their state, with the exception of: Atlanta, Baltimore, Boston, Chicago, Cincinnati, Cleveland, Dallas, Denver, Detroit, Honolulu, Houston, Indianapolis, Las Vegas, Los Angeles, Miami, Milwaukee, Minneapolis, New Orleans, New York, Oklahoma City, Philadelphia, Phoenix, Pittsburgh, St. Louis, Salt Lake City, San Antonio, San Diego, San Francisco, Seattle, Washington.

On first mention, write out United States. On subsequent mentions, US is fine. The same rule applies to any other country or federation with a common abbreviation (European Union, EU; United Kingdom, UK).

URLs and websites

Capitalize the names of websites and web publications. Don’t italicize.

Avoid spelling out URLs, but when you need to, leave off the http://www.

Writing about Mailchimp

Our company’s legal entity name is “The Rocket Science Group, LLC.” Our trade name is “Mailchimp.” Use “The Rocket Science Group, LLC” only when writing legal documents or contracts. Otherwise, use “Mailchimp.”

Always capitalize the first “M” and lowercase the “c” in Mailchimp.

Refer to Mailchimp as “we,” not “it.”

Capitalize branded terms, like Mailchimp Presents. We also capitalize pricing plan names (Premium, Standard, Essentials, and Free) to distinguish them from generic use of those adjectives.

Don’t capitalize descriptive product or feature names, like email or landing pages.

Writing about other companies

Honor companies’ own names for themselves and their products. Go by what’s used on their official website.

Refer to a company or product as “it” (not “they”).

Slang and jargon

Write in plain English. If you need to use a technical term, briefly define it so everyone can understand.

Text formatting

Use italics to for the title of a long work (like a book, movie, or album) or to emphasize a word.

Use italics when citing an example of an in-app Mailchimp element, or referencing button and navigation labels in step-by-step instructions:

For MonsterInsights and Popup Maker, use boldface for citing plugin headings and labels.

Don’t use underline formatting, and don’t use any combination of italic, bold, caps, and underline.

Left-align text, never center or right-aligned.

Leave one space between sentences, never 2.

Write positively

Use positive language rather than negative language. One way to detect negative language is to look for words like “can’t,” “don’t,” etc.

Use simple words and phrases

Did you know the US federal government must write in plain language by law? If using simpler words and phrases is good enough for the US gov, then it should be good enough for you.

Here’s an example of making a sentence easier to read by using simpler words and phrases.

In that example, we did the following:

You should also use the most accurate word. In this next example, reproduce is more precise than replicate.

When in doubt, look it up. Here’s how the New Oxford American Dictionary defines replicate and reproduce.

Replicate: To make an exact copy.

Reproduce: To produce again or create something very similar.

The US Government’s Dirty Dozen

Check out the US government’s list of simple words and phrases. Here’s their top 12 (dirty dozen) from that list.

  Avoid Use Instead
1. addressees you
2. assist, assistance aid, help
3. commence begin, start
4. implement carry out, start
5. in accordance with by, following, per, under
6. in order that for, so
7. in the amount of for
8. in the event of if
9. it is (omit)
10. promulgate issue, publish
11. this activity, command us, we
12. utilize, utilization use

Microcopy (UX Writing)

When writing microcopy, pay extra attention to these guidelines:

Remember to write in plain English. Here’s an excellent example from Material Design by Google.

We’ll throw in one tip that’s specific to UX writing.

Ask questions rather than always giving commands

We’re not saying to go overboard. Instead, try finding a sweet spot to balance questions and commands. Here’s some inspiration from Slack.