Skip to main content

Utility (external) navigation

Grammar and mechanics

Adapted from mailchimp’s guide under a CC-BY-NC-4.0 license.

Table of contents

  1. Introduction
  2. Basics
  3. Guidelines
    1. Abbreviations and acronyms
    2. Active voice
    3. Capitalization
    4. Contractions
    5. Emoji
    6. Numbers
    7. Dates
    8. Decimals and fractions
    9. Percentages
    10. Ranges and spans
    11. Money
    12. Telephone numbers
    13. Temperature
    14. Time
  4. Punctuation
    1. Apostrophes
    2. Colons
    3. Commas
    4. Dashes and hyphens
    5. Ellipses
    6. Periods
    7. Question marks
    8. Exclamation points
    9. Quotation marks
    10. Semicolons
    11. Ampersands
  5. People, places, and things
    1. File extensions
    2. Pronouns
    3. Quotes
    4. Names and titles
    5. Schools
    6. States, cities, and countries
    7. URLs and websites
    8. Slang and jargon
    9. Text formatting
    10. Write positively

Introduction

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.

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

The guiding principle behind these guidelines is trueness to form: a word, phrase, number, etc. should look like what it is. The more a date, time, phone number, quote, or similar looks to the user like its affordance, the more likely the user will understand and consume that information.

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.

[email protected]

Don’t capitalize random words in the middle of sentences. Here are some words that we never capitalize in a sentence.

  • website
  • internet
  • online
  • email

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.

Dates

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

Saturday, January 24

Sat., Jan. 24

Decimals and fractions

Spell out fractions.

Yes: two-thirds

No: 2/3

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

Ranges and spans

Use a hyphen (-) to indicate a range or span of numbers.

It takes 20-30 days.

Money

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

$20

$19.99

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

¥1 €1

Defer to Nick Kolenda’s Pricing psychology when setting the price of any product on the site. The goal for any price should be:

  1. Ensuring an acceptable profit margin
  2. Being honest
  3. Enticing the prospective buyer

Telephone numbers

For US phone numbers, use the familiar format with the area code in parentheses:

(248) 721-0350

For any international number, precede with a + followed by the country code and number with no spaces. If a regional/local formatting standard is known, use that.

+44 0800 328 1700

Temperature

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

98°F

Time

Use numerals and AM or PM, with a space in between. Always add minutes, even on the hour, as it makes times within text far more recognizable and skimmable.

  • 7:00 AM
  • 7:30 PM

Use a hyphen between times to indicate a time period.

7:00 AM–10:30 PM

Specify time zones when writing about an event or something else people would need to schedule. Abbreviate time zones within the continental United States as follows:

  • Eastern time: ET
  • Central time: CT
  • Mountain time: MT
  • Pacific time: PT

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.

  • the 00s
  • the 90s

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

  • the 1900s
  • the 1890s

Punctuation

Punctuation marks, such as the colon, should be outside of bolding or emphasis if they are at a boundary. Other punctuation similarly should be “programmer style”, where commas are outside of quotes and the like. This is not exactly to AP/MLA/Chicago style standards, but matches the personality of our voice.

In some cases, such as apostrophes, quotes, and others, there exist ‘smart’ marks that are curly or otherwise-affected. Using these marks rather than plain or straight quotes is left to your discretion — plain marks are entirely acceptable in all usages.

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.

  • The donut thief ate Sam’s donut.
  • The donut thief ate Chris’s donut.
  • The donut thief ate the managers’ donuts.

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.

Erin ordered 3 kinds of donuts: glazed, chocolate, and pumpkin.

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

I was faced with a dilemma: I wanted a donut, but I’d just eaten a bagel.

Commas

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

Yes: David admires his parents, Oprah, and Justin Timberlake.

No: David admires his parents, Oprah and Justin Timberlake.

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

Dashes and hyphens

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

  • first-time user
  • Monday-Friday

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

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

Multivariate testing — just one of our new Pro feature — can help you grow your business.

Austin thought Brad was the donut thief, but he was wrong — it was Lain.

Ellipses

Ellipses (…) can be used to indicate that you’re trailing off before the end of a thought. Use them sparingly. Don’t use them for emphasis or drama, and don’t use them in titles or headers.

“Where did all those donuts go?” Christy asked. Lain said, “I don’t know…”

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

“When in the Course of human events it becomes necessary for one people to dissolve the political bands which have connected them with another and to assume among the powers of the earth, […] a decent respect to the opinions of mankind requires that they should declare the causes which impel them to the separation.”

Periods

Periods go outside of quotation marks, programmer-style. They go outside parentheses when the parenthetical is part of a larger sentence, and inside parentheses when the parenthetical stands alone.

Christy said, “I ate a donut”.

I ate a donut (and I ate a bagel, too).

I ate a donut and a bagel. (The donut was Sam’s.)

Leave a single space between sentences.

Question marks

Question marks go inside quotation marks if they’re part of the quote, and outside otherwise. 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 when part of the quote, or outside otherwise. 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 outside quotation marks when terminal. 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.

Who was it that said, “A fool and his donut are easily parted”?

Brad said, “A wise man once told me, ‘A fool and his donut are easily parted.’”

Use single quotes for single words or hyphenated phrases. For multi-word quotations, use double quotes on the outside and single quotes within. Avoid triple-nested quotes whenever humanly possible.

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.

  • Ben and Dan
  • Ben & Jerry’s

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.

  • GIF
  • PDF
  • HTML
  • JPGs

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

  • slowclap.gif
  • ben-twitter-profile.jpg
  • ilovedonuts.html

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.

Quotes

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

“Using Mailchimp has helped our business grow,” says Jamie Smith.

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”).

  • Marketing team
  • Support department

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

Our new Marketing Manager starts today.

All the managers ate donuts.

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.

Georgia Institute of Technology, Georgia Tech

Georgia State University, GSU

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, write the entire URL including https://www. and the like, so the address is recognizable and skimmable.

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 indicate the title of a long work (like a book, movie, or album) or to emphasize a word.

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.

Yes: To get a donut, stand in line.

No: You can’t get a donut if you don’t stand in line.