Content

Follow these guidelines when writing copy for our product. Have questions? Talk to Richard at richard@customer.io.

Goals

  • Clear, but friendly: We won’t shy away from technical concepts, but want to retain our personality and not overcomplicate before we need to.

  • Consistent: There are a lot of similar-but-distinct terms in our product. Let’s reinforce users’ understanding of them by using them consistently.

  • Concise: We often don’t have a huge amount of space to convey a difficult concept.

Active, not passive

We want to use active voice, because it is often clearer and less wordy. To use a simple example:

  • Active: We are sending emails.

  • Passive: Your emails are being sent.

Using active voice means that there will be less ambiguity in which action is being performed, and by whom.

Colloquially friendly, not overly technical

Yes, there’s a lot of complexity to our product. However, there are diminishing returns when it comes to technical clarity; we end up using more words, and customers have to redefine concepts they already understand.

Be approachable. This does not mean exactly technically correct, and that is okay. Provide a link to documentation and think of the regret test; is the user likely to regret this action if they don’t understand precisely what is happening behind-the-scenes?

Users should be able to understand the most basic function of a feature/workflow in a friendly way that is consistent with their mental model.

Example: When users are deleting people, they are technically deleting IDs, but we maintain the “people” terminology for clarity and continuity’s sake.

Capitalization

Headings

Use sentence case for all headings and CTAs:

  • Capitalize the first word of a heading

  • Capitalize proper or trademarked nouns (names of products, countries, or people)

  • Lowercase for everything else

Product and feature names

If a feature isn't unique to Customer.io, don't capitalize it. If it's unique and marketable as its own product, capitalize it.

Trademarks

Respect the usage guidelines of any third-party property. Review the third party’s brand guidelines to make sure you are using the company’s name, product names and logo correctly.

Job titles

Job titles are capitalized when they come before or after a person’s name. When using a job title without a person’s name, don’t capitalize the job title.

Punctuation

Periods

Periods often end up in places that shouldn’t and are omitted at strange times. In general, don’t use periods in interface copy unless it's a full sentence description.

Ampersands

Don’t user ampersands (&). Spell out the word "and." Only exception for now is in the left navigation menu.

Apostrophes

Use apostrophes to form possessives:

  • Plural nouns that end in s (customers’, cards’)

  • Singular nouns: add s even if they end in s (bus’s)

Always use apostrophes, not (vertical) straight quotes.

Talking about people

Do use: When we’re talking about the end-user, the default term is People/Person. There are some situations in which this cannot be used, or feels ambiguous or awkward. In those cases, use Recipient.

Don't use: Customer, User, Email (this is occasionally used to refer to a specific user), profile/id (unless specifically relating to billing or API documentation).

Talking about messages

We don’t want to use the term “Action” anymore. “Message” includes anything end-user facing: Email, SMS, Push, Slack (even though this is often internal, it still might go to someone). Webhooks and Attribute updates can be referred to by name. If we want to refer to anything in the workflow, use “Workflow item."

Situational: Writing copy for…

In navigation, use Title Case and be as clear as possible about the purpose of the area that the user is heading to. No need for personality here— just clarity.

Buttons

  • Buttons are in sentence case and should always contain actions.

  • Clear and concise

  • Capitalize proper nouns (Campaign, Newsletter, Slack Message etc.)

  • No ellipses in buttons; they aren’t required to indicate further action. Please avoid special characters such as & or —

  • No more “Next: [noun]”

    • If this is controversial, we can fall back to ‘[noun] >’

Modals

Any explanatory text in modals should follow the “colloquial, but clear” mandate: we don’t have to go in-depth on functionality or be technically precise, but any copy should be correct. People skim; they do not read. To aid usability:

  • Start with the takeaway or conclusion.

  • Use bullet points where you can.

  • Highlight key words (but not too many).

  • Be concise, even if it means taking some nuance out. Write a lot, and then cut the words in half.

  • Link to documentation if we need to.

When deleting or warning, customers should very clearly understand the consequences of their action, and whether or not it can be undone. This must be stated first.

Tooltips

  • Assertive but colloquial.

  • Active voice!

  • If they’re used in a situation where the user needs help, tell them 1) what the problem is, and 2) reasoning, an alternative, or a solution as applicable.

Tables

Use sentence case for table headings, and be as concise as possible.

Input placeholders

A placeholder in a form field should/can offer an additional example, but never instruction or mandatory information, which should be placed in the label or other instructional text, for accessibility reasons.

We've got a lot of inconsistency here, so we'll be clearing this up as we go:

A not-so-great-example: The People page The instructional text is above the field, but doesn’t really have enough of an association with the field below it, which is the only explicit instructional text.

A bad example: “Edit Displayed Attributes” [Example]

A bad example: Segment searches [Example]

Errors, warnings, and “FYIs”

  • Takeaway first, in plain language. Why should the user care?

  • For errors, answer the questions: “What went wrong?” and “What can I do?” in that order

  • Remember to use active voice

  • Don’t over-communicate.

  • Indicate tone upfront early in the copy, commonly used:

Deletion

  • When a user is about to delete or destroy something, tell them:

    • What is being deleted

    • The consequence of that deletion

  • Reinforce with ‘No, [x]’ and ‘Yes, [x]’ when a choice is being made

  • No double negatives.

A workflow item

Text within workflow items should not be explanatory. This is due to space constraints.

Indicating time

When we want to indicate when something has happened, we use several time formats. Usage depends on when something happened.

  • ...today: “Today at 00:00 am/pm” OR “x seconds/hours/minutes ago”

  • ...in the past 24 hours: “Yesterday at 4:12 am/pm”

  • ...over 24 hours ago: “Mar 20, 2018”

  • ...over 24 hours ago, and we want to be hyper-specific: “Mar 20, 2018 at 12:30:00 pm (EST)”

For any date, we have the option to have the hyper-specific format in a tooltip.

Glossary (WIP)

  • Campaign

  • Event Triggered

  • Segment Triggered

  • API Triggered Broadcast (“Broadcast”)

  • Trigger

  • Newsletter

  • Event

  • Email

  • Push

  • Slack Message

  • Twilio SMS

  • Segment

  • Filter

  • Condition

  • A/B Test

  • Split test

  • Action

  • Webhook

  • Workflow

  • Workspace

  • Profile

  • Attribute

  • Event

  • Page

  • Device

  • Spam

  • Unsubscribed

  • Bounced

  • Suppressed

  • Failed

  • Conversion

  • Goal

  • Content

  • Drag-and-drop

  • Rich text

  • Code

  • Layout

  • Active

  • Archived

Tips for Writing

Get words down quickly

  • Generate ideas with no constraints. Try mind mapping, free writing (go for quantity not quality), or brainstorming with others

  • Get something down. "Save the things" is better than "Button label"

  • Skip the details (e.g. proper nouns). Especially if looking for the details means leaving the writing environment. Better to stay writing and fill in the details later.

  • Keep your fingertips on the keyboard.

  • Measure progress by number of words.

  • Try having a physical environment for writing (and a separate one for editing)

Practice ABCs: Accuracy, Brevity, Clarity

  • Accuracy: For example, what does the button do? Does it "Save", does it "Create", does it take you to another page?

  • Brevity: Aim for it, but don't sacrifice accuracy or clarity. Avoid starting with brevity, but start with a longer, more accurate and clear set of words. Then trim down.

  • Clarity: Can we...

    • Replace fanciful language with simpler language?

    • Put things in a logical order?

    • Add supporting information?

    • Add examples to reinforce?

    • Delete things that don't support the main idea?

    • Define concepts that users might be unfamiliar with?

Questions to ask yourself if you're stuck

  • What's the purpose of the copy? Is it to explain? to motivate? to warn? What is the one thing you want to say?

  • What is the benefit of this feature? What is the value of this? What is the outcome that will be achieved? What is the call-to-value v. call-to-action?

  • How can we set expectations? What's going to happen? What's the user input needed? What is the product going to do? How long will it take?

  • What's the story or narrative? What are they trying to accomplish?

  • Where is the user coming from? What do they already know at this point? What don't know they know? What questions will they have?

Tips for Editing

What to evaluate:

  • Focus: Does every word serve a clear purpose?

  • Simplicity: Is the structure complex? Is the language plain? Is the concept behind the writing simple? Is it specific?

  • Readability: Is it easy to read? Is the most important point at the top? Is it clear what the next action is? Are the lengths of sentences varied? Can you visualize the copy (perceivable, concrete nouns)?

  • Consistency: Does the writing agree with itself? Are things called the same throughout?

  • Strength: Is an active voice being used? Is it written for the Reader (You) v. Writer (We/Customer.io)?

  • Tone: Does it reflect out guidelines? Can we use the customer's own words?

  • Urgency: Is urgency relevant? Is something severe going to happen?

  • Scale: How important is this? Is it really the best? greatest?

  • Emotion: Is delight and humor appropriate? Should it be serious? Somber? etc.

Specifics to look for:

  • Turn prepositional phrases into adjectives. ...attributes and events in your Customer.io account → your Customer.io attributes and events.

  • Replace adverbs with strong verbs. Boldly change your messages with liquid → Transform your messages with liquid

  • Turn passive voice into active voice. Your emails are being sent → We are sending emails

  • Delete "that" when you can. Emails that were sent → Sent emails

  • Avoid intensifiers (very, really, extremely, etc.). Real-time data is really important to successful messaging → Real-time data is essential to successful messaging

  • Eliminate conjunctions. Send timely and personalized messages to your customers → Send timely, personalized messages to your customers.

  • Avoid starting sentences with “there”. There is a common thought among email experts that using only a person's name doesn't qualify as personalization → Email experts believe using only a person's name doesn't qualify as personalization.

  • Swap nouns for verbs. people who made a purchase → people who purchased

  • Cut wordy phrases. (e.g. In order to → to, In most cases → usually, etc.) In order to send Events... → To send Events.

  • Avoid multiple adjectives. Your customers should be happy and excited to receive your messages → Your customers should be thrilled to receive your messages.

  • Avoid multiple nouns. Create a password reset transactional campaign → Create a transactional campaign for password resets.

  • Use positive description, not negative. The open rate is not high → The open rate is low

  • Avoid “currently”. Your account is currently being setup → Your account is being setup.

  • Skip relative pronouns. Create a campaign that has three emails. → Create a three-email campaign.

  • Reconsider “make”. Using attributes can make your messages more personalized → Using attributes can personalize your messages.

  • Avoid creating new names. Product terminology can be hard to understand. Don't expect people to learn new nouns when an alternative exists. Try simply describing them. Name things as a last resort.

If you're stuck, try breaking it down to a three-step process:

  1. Structure – focus on organizing ideas into a logical order.

  2. Clarity – focus on the tips for editing above.

  3. Style – focus on the perfect way to describe existing ideas, don't add any new ideas.

If you're injecting personality:

  • Don't try to make the user feel. Look for the feeling they're already having and just be a part of those.

  • Go beyond the obvious. Add nuance.

    • Example from Slack: When you clear out all unread messages, you're presented with different messages that acknowledge the accomplishment + relief, and ask "what's next?":

      • Everything's sorted! Let's start something new.

      • All caught up. What's next?

      • That's that. You're good to go.

      • Done and done.

  • Pick your spots to add personality. Customers trust us for a serious task: sending messages to their customers.

The difference between the text and conveyed message:

Logged in from a new device email

Copy is providing all information necessary to user. Nothing is inherently wrong, there's simply a login from a new device. However, this wall of text + "Unrecognized login" subject line induces a moment of panic and fear. Users reached out to support before even reading the email.

This example comes from Designing like a writer: how language can elevate your work by Andrew Schmidt

Last updated