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.
- Write like a human. Default to a clear but conversational voice.
- Write for one person. Know your audience and what they care about.
- Write with one goal. Know what you want your audience to learn or what you want them to do next.
- Write less and say more. The fewer words you can use to make a point, the better.
- Write with consistency. Follow the guidelines in this section. Use these rules to give your content the stability and structure it needs to accomplish its goals.
Mechanics and Style
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:
- CEO, CFO, CTO
- RSS, API, HTML, CSS
- NASA, FBI, CIA
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.
- An FBI agent, (eff-bee-eye)
- A UFO flew by, (yoo-eff-oh)
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
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 email@example.com.
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.
- Isn’t, the “o” in “is not” is replaced by an apostrophe
- Y’all, the “ou” in “you all” is replaced by an apostrophe
- Cookies ‘n’ cream, the “a” and “d” in “Cookies and cream” are both replaced by apostrophes
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.
- On Thursday, August 10, we’re hosting a webinar.
- Her birthday is June 25.
- We’re organizing a meetup on Tuesday, July 16, 2019, for automation lovers.
Abbreviate when there are space constraints:
- Fri., Oct. 13
- Aug. 5, 2018
Don’t abbreviate March, April, May, June, or July. They’re short enough already.
Abbreviate decades within the last 100 years:
- In the ’90s
- In the 1870s
Replace numbers you remove with an apostrophe. For ’80s, the “19” in “1980s” is replaced by an apostrophe.
For headline levels one and two (H1 and H2) we follow general title case guidelines:
- adjectives (orange, helpful)
- adverbs (quickly, easily)
- nouns (dog, truck)
- pronouns (she, our, themselves)
- verbs (run, connect—don’t forget helping verbs like is, have, and are)
- subordinate conjunctions (once, as, if, when they connect unequal parts of a sentence)
- prepositions with five letters or more (through, without, above)
- articles (a, this, the, that)
- coordinating conjunctions (and, but, or)
- prepositions with fewer than five letters (from, over, with) but not through or without)
- the “to” in an infinitive (For example, “How to Play Guitar”)
- Always capitalize the first and last word of the headline, even if it’s a word that you wouldn’t usually capitalize.
- Capitalize the first word after a colon, no matter what
- Use numerals like 25, 6, and 4 for all numbers; never write them out
- Use single quotes for any quoted piece of text
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:
- Capitalize the first word of the headline
- Capitalize the first word word after a colon, no matter what
- Capitalize titles and proper nouns
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.
- graphic designer Adam Kaplan
- pharmacist Erin Kelley
- lead engineer Bryan Helmig
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:
- Sir Paul McCartney
- General Grievous
- President Selina Meyer
However, lowercase formal titles if they appear after the person’s name:
- Daenerys Targaryen, princess of Dragonstone
- Anthony Garcia, mayor of Gotham
When in doubt, just move the title after the name and lowercase it.
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:
- Addresses. “102 Pike St., Seattle, Washington 98101”
- Ages. “George Washington died at age 67.”
- Big numbers. “3 billion”, not “three billion” or “3,000,000,000”
- Dates. “March 15”, not “March fifteenth”. “The ’90s”, not “the nineties”
- Money. “$9.75”, not “nine dollars and 75 cents”
- Times. “5 p.m.” and “6:30 a.m.”, not “5 o’clock” or “six thirty”.
- Exception: use “noon” and “midnight” instead of “12 p.m.” and “12 a.m.”, respectively.
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.
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:
- Jill’s team is working on that project.
- Apple’s new iPhone leaked last night.
- He raves about Julius’s design skills.
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.
- I got mostly A’s and B’s in high school.
- The judges gave her performance 10s across the board.
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:
- the content that follows it could stand alone as a complete sentence.
- the content that follows it it starts with a proper noun. e.g. “Zapier was founded by three friends: Bryan, Mike, and Wade”
- the colon is used in a headline.
Don’t capitalize the first word after a colon if:
- you’re introducing a list of things. e.g. “I was presented with an array of donuts: chocolate, glazed, jam-filled, you name it.”
- the content that follows it is an incomplete sentence. e.g. “I only needed one thing to complete my cake: the frosting.”
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.”
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.
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.
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:
- Compound words (mother-in-law, two-year-old, editor-in-chief)
- Some prefixes, such as “re,” “mid, and “ex,” (Go re-read the mid-year report from the ex-CEO)
- Inventing compound verbs, such as “We Slack-chatted all day” or “He rage-typed a response”
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.)
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.
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.
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.
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 (`).
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.