Grammar

Basics
Active & Passive Voice
You should almost always write in the active voice, but here’s when to use the passive voice:
To avoid referring to yourself or Beans
To make it clear that you didn’t personally take an action or make a decision
If the object (thing being done) is more important than the subject (person doing the thing)
A notification will be sent to your customers after each successful referral.

Beans will send a notification to your customers after each successful referral.

Contractions
Contractions are abbreviated words. Contractions are acceptable in formal writing under these
circumstances:
When using a direct quote from an individual
When using an idiom that already contains a contraction

Don’t count your chickens before they hatch

You’re all set up

It’d be a good idea to place an ad this weekend.

There’re 10 products in this collection.
That’ll make sure you are all set up
You gotta set up your loyalty program before Black Friday

Plain Language
Use words and language that our merchants use. Avoid jargon or technical terminology. Make
sure each sentence has a single focus and keep them short. Aim for a Grade 7 reading level.
These products aren’t getting a lot of views, but visitors are adding them to their carts
 These are your less popular products with the highest add-to-cart conversion

Capitalization
Title and Headings
Use word case for the article title and sentence case for all other headings.

Article title example:

Make Your Marketing Intelligent

Make your Marketing Intelligent

Section headings example:

Connect every marketing interactions

Connect Every Marketing Interactions

Trademarks
Respect the usage guidelines of any third-party intellectual property. For example, in US
communications, Apple Pay requires you to include the trademark symbol (™) the first time
Apple Pay appears in body copy.
Review the third party’s brand usage guidelines to make sure you are using the company’s
name and logo correctly.

Job Titles
Job titles should be capitalized when they come before or after a person’s name. When
referring to a job title without referencing a name, don’t capitalize the job title.

Jane Smith, Content Strategist

 Jane Smith, content strategist

The content strategist designed the information architecture.

The Content Strategist redesigned the information architecture.

Lists

Use a bulleted list when items are related but sequence or priority doesn’t matter.
Use Beans to:
- Increase retention
- Save time
- Create a better customer experience

Use Beans to:

- increase retention,
- save time, and
- create a better customer experience.

Use a numbered list when item sequence or priority does matter, such as step-by-step
instructions.
To setup Beans:
1. Install the app in your Shopify store
2. Approve all the required permissions
3. Follow the onboarding tutorial

To setup Beans:
1. Install the app in your Shopify store and approve all the required permissions
2. Follow the onboarding tutorial
Additional tips for lists:
List items always start with a capital letter.
Capitalization and punctuation rules apply to both bulleted and numbered lists.
Introduce bulleted lists with a colon or a heading.
Don’t use commas at the end of list items (for bulleted or numbered lists).
If any list item contains two or more sentences, punctuate all list items.
If all list items are one sentence or fragments, don’t punctuate.
Never put a comma or semicolon at the end of a bulleted or numbered list item. Treat each
list item as a self-contained piece of information.

Dates, numbers, and measurements

Date
When possible, use the month’s full name, for example, October. If there are space constraints,
use 3-letter abbreviations, for example, Oct. Don’t write dates numerically, for example, 07-02-
14. Don’t use ordinal indicators, which are words representing position or rank in a sequential
order (1st, 2nd, 3rd, and so on).
Thursday, October 15, 2015

10/15/15

Time
Use the 12-hour clock, followed by am or pm.
Include a space after the last number, for example, “Your package will arrive at 12:35 pm”.
Adding the space helps with formatting for English-speaking markets outside of North
America, so we use it for North American usage as well.
To show a time range, use an en dash and include the am/pm after both times, for
example, 3:00 pm–4:00 pm.
If indicating both the date and time, separate them with the word “at”, rather than with a
comma.
Include a time zone only if it’s necessary, such as for an event listing.
Use the time zone’s abbreviation following the am or pm, for example, 4:00 pm NZT.
Thursday, October 15, 2015 at 2:00 pm EDT
 2015-10-15, CT 2:00P.M.

Currency
When including currency with a price, the currency comes after the dollar amount.
$10,000 USD

USD$10,000
$10KUSD

Numbers
In general, use numerals. If the number is below 10 and not integral to the sentence, spell it out
in full.
Here are 2 marketing campaigns you can use.
You no longer need to track shipments in two places.

Here are two marketing campaigns you can use.

You no longer need to track shipments in 2 places.

Use commas for numbers with four or more digits. Whenever possible, don’t truncate numbers.
12,000
9,344
1,800,887

12 k
9344
1.8 m

Use an en dash without a space on either side for number ranges:

 5–10 products
October 15–31
2005–2015
$0.00–$49.99

5 – 10 products
October 15 – 31
2005 – 2015
$0.00 – $49.99

Punctuation
Colons
Avoid using colons in sentences. If you need to use one, don’t capitalize the first word after the
colon unless it’s a proper noun. Introduce bulleted lists with a colon.

Your store accepts payments with GoCoin and Alipay.

Your store accepts payments with: GoCoin and Alipay.

Commas
Use the oxford comma (also known as the serial comma) in sentences. There should be a
comma after every list of 3 or more items (unless you’re using a bulleted or numbered list).
Beans is an app that handles your loyalty program, email marketing, and social
media.

Beans is an app that handles your loyalty program, email marketing and social
media.

En-dashes and Em-dashes

Use an en dash with no spaces in between (–) for a fixed range of numbers.
 2006–2013

2006 – 2013

Use an em dash only if you can’t make your message clearer by splitting it into two sentences.
Use an em dash without a space on either side (—).
Choose your theme’s colors, typography, and pictures—all in one place.

Choose your theme’s design—colors, typography, and pictures—all in one place.

Exclamation Marks
Avoid exclamation marks—only use them for really really exciting things. If you absolutely have
to, limit yourself to one exclamation mark per article.
You’ve launched your first online store!

You’ve updated your product title!

Hyphens
Use hyphens to:
Form compound modifiers: two words that combine to modify or describe the noun that
follows
Join prefixes and suffixes only if there are two vowels beside each other. Never use
hyphens in the words ecommerce and email.
Start your free, no-risk, 14-day trial.

Start your free, no risk, 14 day trial.

 Re-order
ecommerce

Reorder
e-commerce

Quotation Marks
Use quotation marks to:
Define words (“growth-hacking”)
Quote text
Place commas and periods inside quotation marks.
Always use smart (curly) quotes, not vertical (straight) quotes.
“I see this all the time,” said Mark Hayes.

“It drives me absolutely crazy”, said Mark Hayes.

Bold
When in doubt, don’t bold. Use bold sparingly and only where strong emphasis is required.
Don’t use bold to emphasize proper nouns, create a heading, or emphasize a checkbox title.

You, we, and other personal pronouns

Referring to Merchants
Always refer to merchants as “you”. Don’t put words in merchants’ mouths with phrases that
use “I” or “my”.
Change your email address in your Profile.
 Change your email address in My Profile.

When referring to merchants use the following words:

Merchants
Shop/Store owners
Avoid using the following words. There are synonyms but they don't encompass all use cases:
Retailers (Not all merchants are retailers)
Sellers (This is more adapted to a marketplace such as Amazon)

Referring to Shoppers
Beans creates content for different audiences. One of those audiences is merchants’
customers. A customer is a person or organization who interacts with a merchant. When
referring to merchants' customers, use the following terms:
Shoppers
Consumers
Customers

Referring to Beans
Always refer to Beans as “we,” but avoid inserting Beans into the content as much as possible
(except when a human is taking action, such as reviewing a request).
Pinterest Buyable Pins will be available in the coming weeks.

We’re making Pinterest Buyable Pins available in the coming weeks.

Go further
Here are some style guides that we appreciate. Be aware that this style guide supplements any
instructions you may find it the guidelines listed bellow. So, only use them as a guide for topics
that have not been discussed in this document
18F Content Guide
Buzzfeed Style Guide
A List Apart Style Guide