Grammar and Mechanics

Good grammar won’t fix crummy writing, but it will help your ideas shine. At Zapier, we write to teach, inform, and empower our users. Grammar helps us accomplish those goals in the most efficient way possible.

The house rules covered here apply to all public-facing content we make. These aren’t rules for the sake of rules—the guidelines in this section give you the tools to write consistent content that helps our users.

Basics

Mechanics and Style

Active voice

Use active voice. It’s more concise and keeps the focus on the subject of the sentence.

In active-voice sentences, the subject of the sentence does something.

Joe won the trophy for eating the most chocolate-frosted donuts.

In passive-voice sentences, the subject of the sentence is acted upon.

The trophy for eating the most chocolate-frosted donuts was given to Joe.

Grammatically, there’s nothing wrong with using passive voice. But passive-voice sentences are wordier, less interesting, and more formal.

There are a couple exceptions. Use passive voice to keep the focus on the victim of an action.

J.T. was chased into the river by an angry wolverine.

Or when you want to highlight the action instead of the subject.

Your subscription was paused because of a failed credit card payment.

Abbreviations and acronyms

Avoid abbreviations and acronyms where you can. They confuse readers and make people stop and think before they continue reading. At worst, your reader won’t understand the acronym you’re using, and they’ll need to go look it up.

If you want to use an acronym or abbreviation, define it first to establish it. Then you can use the acronym or abbreviation in subsequent mentions.

Galactic Donuts runs all purchases through a point of sale (or POS) system.

We love writing about customer relationship management (CRM) tools.

If the acronym is more widely used than the full version, use the acronym instead and don’t worry about spelling the full version out. For example:

When “a” or “an” precedes an abbreviation or acronym, choose which one you use based on the sound of the abbreviation, not the first letter of the abbreviation.

Capitalization

In body text, capitalize the first word of every sentence unless it’s camel case (like eCommerce or eBay). If a brand or app uses a lowercase style for their name, capitalize names that are all lowercase.

I bought a new pair of Adidas sneakers

not

I bought a new pair of adidas sneakers

By the way, Zapier, Zap, and Zaps should always be capitalized.

For headlines, use title case on H1s and H2s, and sentence case beyond that. (See the Headlines section for more details.)

Capitalize proper nouns, like someone’s name or a business name.

Never capitalize website names or email addresses.

If you want to learn more about automation, visit zapier.com or send an email to contact@zapier.com.

Contractions

Use ‘em. They help your writing sound friendly and more natural. If you’re inclined to use a contraction like “we’re” instead of “we are” when you read a sentence out loud, use it in your writing too.

Use an apostrophe to represent the letters we’re removing from the contraction.

Dates and times

Spell out the day of the week and the month. Use a numeral for the day of the month. Don’t add rd, th, or st to the end of your numeral.

Only include the year when it’s necessary to frame a story or when the date is more than 6 months in the future.

Abbreviate when there are space constraints:

Don’t abbreviate March, April, May, June, or July. They’re short enough already.

Abbreviate decades within the last 100 years:

Replace numbers you remove with an apostrophe. For ’80s, the “19” in “1980s” is replaced by an apostrophe.

Headlines

For headline levels one and two (H1 and H2) we follow general title case guidelines:

When in doubt, use this capitalization tool to get a properly formatted version of your title.

For headline levels three and beyond (H3, H4, H5) we follow sentence case rules:

Jargon and industry phrases

Know your audience. Avoid any words, phrases, or inside jokes that readers won’t catch onto immediately.

Clear writing relies on simple words, so exclude jargon when you can. If you need to include a term or concept, make sure to define it for the reader.

Veronica uses SQL—a programming language that helps you grab info from a database—to create colorful charts and graphs for the marketing team at Costello Industries.

Job titles and formal titles

Lowercase occupational job titles, no matter where the title is placed in relation to the name.

Kim Kadiyala, a marketer at Zapier, talked to astronaut Jeanette Epps about NASA’s upcoming mission to Mercury.

Other examples:

Capitalize common job titles that are acronyms, like CEO.

Capitalize formal titles—a title that someone was elected to, appointed to, or born into—when they appear directly before someone’s name:

However, lowercase formal titles if they appear after the person’s name:

When in doubt, just move the title after the name and lowercase it.

Names

Use a person’s full name when you introduce them in your writing. After the first mention, use the person’s first name only.

Dev Shah didn’t set out to change the cupcake industry. “When someone told me ‘Clash of the Cupcakes’ was affecting global frosting markets, I was floored,” he says. As the longtime host of the world’s most popular baking show, Dev has launched countless cupcake careers.

If you’re writing about multiple subjects with the same first name use the first initial of their last name to avoid confusion.

Numbers and measurements

Always use numerals in the following situations:

Otherwise, write out numbers when they’re less than 10.

Wade ate three pints of cookies ‘n’ cream ice cream.

Chelsea created 12 Zaps in under an hour.

Numbers longer than three digits get commas:

Spell out the word “percent” but keep the number as a numeral. Use a % sign if you’re strapped for space.

5 percent of people don’t care about commas.

Use the full pricing as listed on an app’s or company’s website. For example, use $10.99 instead of rounding up to $11.

And, since Zapier is a global company, include international metrics—such as Celsius and meters—in parenthesis beside the US-based ones.

Punctuation

Apostrophes

Most of the time you’ll use an apostrophe to demonstrate possession or to build a contraction.

Use an apostrophe to show a noun’s possession of something:

If the noun ends in an “s”, add an apostrophe and an s—like “Marcus’s”—to the end of the noun to demonstrate possession.

For contractions, use an apostrophe in place of the letters you’ve left out. Read the contractions section for more details.

Use an apostrophe to make a letter plural, but not a number.

Colons

Colons help you extend sentences with related information. Use them to introduce related ideas, attach sentence fragments, add subtitles, or insert long quotes. Colons can also add a pause for your reader, upping your content’s drama factor.

Capitalizaton can be tricky after a colon. Capitalize the first word after a colon if:

Don’t capitalize the first word after a colon if:

Commas

Use the Oxford comma (also called the serial comma). In lists of three or more items, always include a comma before the last item.

You can use Zapier with MailChimp, Trello, and Slack.

Remember the FANBOYS rule before adding a comma: If you’re connecting two complete thoughts with a coordinating conjunction (For, And, Nor, But, Or, Yet, or So), you should always use a comma before the coordinating conjunction.

I’ll have a cheeseburger, but I don’t want the pickles.

However, if only one part of that sentence is a complete thought, the comma is unnecessary.

I’ll have a cheeseburger but don’t want the pickles.

In the first example, “I don’t want the pickles” is complete with subject and verb, so we add the comma. In the second, “Don’t want the pickles” isn’t a standalone sentence, so we don’t need the comma there.

Also, add a comma after “Also” at the beginning of a sentence, but don’t add a comma after “Or” or any of the other FANBOYS unless it’s followed by a parenthetical:

Incorrect: “Or, you could download this other to-do app.” Correct: “Or, if you want more features, you could download this other to-do app.”

Dashes

Use em dashes (—) in place of commas to enhance readability and separate phrases or even a single word.

Zapier team members—80 people living and working remotely in 13 countries—are building the robot, not being the robot.

Don’t put spaces around em dashes. You can use the Alt+Shift+minus keyboard shortcut to insert an em dash on the Mac.

A note on en dashes: we generally don’t use them, so we don’t set any guidelines around when to use hyphens and when to use en dashes. Default to hyphens.

Exclamation points

Please use exclamation points sparingly! As a rule of thumb, you shouldn’t use an exclamation point more than once in a piece of content. We don’t want to sound too excitable or really angry.

Hyphens

Not to be confused with dashes, the hyphen is used to link words together. When joining two or more words before a noun they modify, it’s called a compound adjective:

The first-place trophy for most Mafia deaths goes to Wade.

One way to tell if a hyphen is needed for the two words is to see if they form a single idea: Without the hyphen, if you remove either of the words, will the sentence still make sense? “The place trophy for most Mafia kills…” does not.

If the two words come after the noun, no hyphen is needed:

Wade got the trophy for first place for the most Mafia deaths.

Compound adjectives can also include numbers and fractions:

We took a 30-minute hike up the mountain, which I only half-wanted to climb.

Hyphens can or must also be used for:

If you’re listing several words that describe the same noun, you can suspend the hyphen.

The itch-, sneeze-, cough-, and headache-relieving tablets are available over the counter.

(Notice there are no hyphens between the words over, the, and counter.)

Semicolons

Try to avoid semicolons. They tend to be difficult to use well and bring a more formal tone to your writing.

Write around them using dashes, commas, and coordinating conjunctions instead.

He promised to send me the details today—and a summary showed up in my inbox at 5 p.m.

Not

He promised to send me the details today; they showed up in my inbox at 5 p.m.

Do use semicolons, though, to clarify a complex list of comma-separated items. For example:

For Elise, Rob, and Melanie, Trello fit perfectly; it gave them task-tracking, color-coded labels, and the ability to assign Cards to the right person.

Use semicolons sparingly. Try to edit around them. When they’re necessary, use semicolons as a more powerful version of a comma, which separates two related thoughts.

Quotation marks

When you’re grabbing a word or phrase directly from another source, set it off with quotation marks.

If you’re attributing a quote to someone, include a comma within the quotation before the attribution.

“Without Zapier, we wouldn’t be able to keep up with all of our orders,” she says. “Now I can focus on what’s more important: growing my business.”

If you’re using a full quote at the end of a sentence, place any sort of punctuation inside the quotation.

Adam was frustrated, too. “The worst thing about the whole thing was the lack of pie. Who plans a party without any pie?”

For partial quotes, even at the end of sentences, punctuation should go outside the quotation.

Even with the dessert snafu, Kenneth More called the party a “night to remember”.

Quoting people and publications

Quotes give your writing color and authenticity. If your quote doesn’t add personality or provide important details, leave it out.

When you’re quoting a person or publication in a piece of content, make sure that quote is accurately attributed. Use present tense (says, not said):

“I love using Zapier to automate my work,” Sean says.

Try to introduce the quoted person before you quote them. This:

Selena, a manager at Galactic Donuts, uses Zapier to track orders. “It makes my life so much easier,” she says.

Is preferred to:

“Zapier makes my life so much easier,” Selena, a manager at Galactic Donuts, says.

Keep the focus on the person who said the quote by placing their name directly after it, before “says”. Use “he”, “she”, or “they” when you’re quoting the same person in quick succession and it’s clear that the quote belongs to the same speaker. If the quotes are close enough, you can leave out the second “says” entirely.

“‘Rumours’ is my favorite Fleetwood Mac album,” Carlin says. The Grammy-winning 1977 record is a staple in any music fan’s library. “You can’t listen to ‘Second Hand News’ without singing along.”

Accurate quotes are important, but we also want to make our subjects look good. Feel free to edit out the “ums” and “uhs” from a direct quote. It’s ok to tweak the grammar in a quote, but use caution not to change the quote’s meaning. When in doubt, ask your subject for clarification or approval.

Software instructions

Capitalize and italicize menu items, such as Save or File.

Press Save in the web clipper to create a new note in Evernote.

For keyboard keys and keyboard shortcuts, surround the keys with a backtick (`).

Control + Shift

This calls out those words so they look like keys on the page (neat!). Spell out Control, Command, Alt, and other keys rather than using their symbols.


Writing About Partners and Other Companies

When writing for or about partners, default to their style. Write Tweet, not tweet. Write Trello card, not Card or task. Follow regular capitalization rules at the beginning of sentences.

If you don’t know, ask, and when in doubt skew towards understanding. If an app lets you create “things”, capitalize Things to let the reader know that this is a specific feature of the app, and to avoid confusion.