Brand

Writing style

Twilio is a tool someone uses to bring an idea to life. This style guide functions in a similar manner. You, a Twilion, have an idea you want to express in words. This style guide shows you how to do that on any platform, with visual examples and do's and don'ts included.

The two most important principles of the Twilio voice

Before we dive into the style guide, let’s review two really important principles that guide Twilio’s Brand Voice: write like a human being and be accurate and authentic.

1. Write like a human being

Twilio’s writing style is approachable and human. We speak confidently, but not colloquially. We are exacting without being robotic.

Humans are going to read the words you write. Write your copy with a specific person, or group of people, in mind. Have an idea of what you want them to know and what action they should take.

Do

SMS built for developers. Code in the language you know to programmatically send messages to millions.

Don't

Every message is a big opportunity. Our SMS API helps you extend your reach and get results with access to every messaging-enabled mobile number.

2. Accuracy and authenticity reign supreme

Writing accurately means you know the ins and outs of the product or subject you’re writing about. Writing authentically means that you speak truthfully about that subject.

There is no room in Twilio’s Voice for approximations or half truths.

Do

Twilio deploys over 55,000 automated tests across our platform, ensuring your video app works in every browser, across all releases of WebRTC, past, present and future.

Don't

The most comprehensive set of mobile solutions for WebRTC. Get your mobile app up and running quickly with advanced features, control, and wide device support.

How tone and voice work together

You now understand the biggest tenets of the Twilio Voice. The Twilio Voice principles apply everywhere. What you say to an enterprise marketing executive and a solo developer might differ, but the principles guiding your speech remain the same.

The difference between voice and tone

The difference between voice and tone is that voice is constant and tone is situational.

Your voice is your identity. It’s fixed. It’s constant. Your tone is an expression of your identity. It fluctuates when appropriate and often depends on context.

Put it this way - you use a specific tone talking your friends in a late night heart-to-heart. That’s you. That’s your voice. You use a different tone when going through a performance review with your boss in the early morning. That’s still you. That’s still your voice. You’re just using a different tone.

Adopting a different voice for every different situation you encounter leaves you rudderless.

 

Keys to writing effectively

Before you start writing you should ask and answer these questions:

  • Who is your audience?
  • What is the most important thing you want them to know?
  • What do you expect them to already know?
  • What value does the product, service, or update you’re writing about provide?
  • What tangible part of the product that provides that value?
  • Are you presenting your information in a logical order?

It is vitally important that you know who your audience is in order to structure a page correctly and hone your message effectively. To illustrate this, let’s take a hypothetical example in which you have to explain Twilio to someone who has no idea what Twilio is.

The Castaway test

You’re trying to explain Twilio to Chuck Noland, Tom Hanks’ character in Castaway. He has just been rescued from a remote island. He has no idea what an API is. Starting out explaining that an omnichannel platform is Chuck’s best option to reconnect with the world would make no sense to Chuck. Chuck has no idea what omnichannel is, why would he think it provides value? Starting out explaining to Chuck that Twilio is like a phone, but more powerful, might make more sense to him.

This exercise is to say: Know who your audience is. Determine what they know. Start from a context that makes sense to them. Guide them deeper into new information. Here are the best ways to do just that.

Author guidance

Resources and rules

Use active voice

Always write in active voice. In active voice, the subject of the sentence performs or initiates an action. In passive voice, the subject of the sentence is the recipient of an action — or worse — the action exists on its own and it’s unclear who initiated the action.

Do

An incoming text message triggers a callback.

Don't

A callback is triggered.

Capitalization

We use sentence case everywhere — in headers, subject lines etc. The only exception is proper nouns and the Console but we’ll get into that later.

When you’re writing for Twilio, a majority of the proper nouns you capitalize will be products. Before you capitalize, ask “Has Twilio branded this product as something it owns?” If the answer is no, you’re probably incorrectly capitalizing a generic term that’s commonly used in the industry, but not owned by one particular entity.

Do

I love Twilio Runtime’s serverless environment.

Don't

I love Text Messages.

Style tips

The way we write influences our style and thus how readers experience our brand. So, if we do the linguistic equivalent of sporting Crocs with socks, we’re not presenting the brand correctly. So, here are a few things we don’t do.

Don’t open with a rhetorical question

Setting the stage for a reader is hard. But, it’s doable and it’s rewarding when you do it well. Better copy drives sign-ups, time on page, and conversion.

Think about who your audience is, what they want, what problem you’re helping them solve, and how to present that information as succinctly and personably as possible.

Rhetorical questions are shortcuts around this hard work. Don’t take the shortcut.

Do

Twilio lets you send messages around the world with a few lines of code. Reach customers directly using the Twilio SMS API.

Don't

Are you tired of sending messages in a bottle, hoping they’ll make it to your customers? Well we have the solution for you — Twilio SMS!

Write in a friendly, approachable tone

There’s no special professional writer hat you put on before you start writing. You don’t have to write how you think another marketer, engineer, or admin sounds. Write using your natural voice, then apply the Twilio voice principles.

It’s much easier to edit down copy that has energy and voice than it is to try to resuscitate some dry, strained copy.

Do

Twilio reaches millions of developers around the world. We’re constantly inspired by the new ideas the developer community brings to life.

Don't

Millions of developers have used Twilio, globally. The applications which developers build using Twilio are exciting.

Critical places we write

Whether you write for the console, blog, or PR, here are a few tips to hone your writing for your specific medium.

Console

Writing in the Console falls into two primary categories, or a mix of these two:

  1. Guiding a user to accomplish a task they desire
  2. Informing the user of a task that need their attention

In each of these scenarios, you need to have a clear understanding of what the user currently knows, what you’d like them to know, and where they are in the journey of either informing or accomplishing a task.

Here are some style tips for writing in the Console.

Phrase questions / statements in the user’s context

Do

How satisifed are you with Twilio?

Don't

How would you rate your satisfaction using Twilio Studio?

Capitalize conservatively

There’s a difference between a product, a product feature, and a task the product accomplishes. Just because a feature or task is adjacent to a product like Twilio Studio, does not mean that its tasks should be capitalized in the same way the product is.

Refer to the product capitalization rules above.

Do

You can build drag and drop applications with Twilio Studio.

Don't

You can build Drag and Drop Flows with Twilio Studio.

Lead with the information that’s most important to the user

In longer flows, like signing up for Twilio for WhatsApp, or any third party service, users have their eyes on one outcome - getting their app up and running.

When describing a multi-faceted flow to get that user up and running, refer to their progress in terms of how close they are to their goal.

Do

Please confirm your business name to proceed with your Twilio for WhatsApp registration.

Don't

Your business registration is confirmed. Please proceed with Twilio for WhatsApp registration.

Don’t abbreviate

Spell out the product or place you’re describing. We don’t use abbreviations because they read as unprofessional, or coloquial.

Do

Account, Facebook, registration

Don't

acct, FB, reg

Error messages

In longer flows, like signing up for Twilio for WhatsApp, or any third party service, users have their eyes on one outcome - getting their app up and running.

When describing a multi-faceted flow to get that user up and running, refer to their progress in terms of how close they are to their goal.

Do

Please confirm your business name to proceed with your Twilio for WhatsApp registration.

Don't

Your business registration is confirmed. Please proceed with Twilio for WhatsApp registration.

Blog

Readers of the Twilio blog are looking for specific content. They’re searching for a solution, clicking through from a HackerNews thread, Twitter, or a StackOverflow post. The majority of readers are not browsing through twilio.com/blog in hopes they’ll find a post that interests them, they’re searching for an interest they already have.

Prioritize these things in your post
  1. The hook
    The first paragraph of your blog post that the reader will consume and use to determine if they’ll stay to read your blog post, or disappear into the internet.
  2. Brevity
    There’s no hard coded character count on a blog post. That doesn’t mean you should write a novel.  Unnecessary copy will drain a reader’s attention span and cost you time on page statistics. Get your point across in the fewest words possible.
  3. Clarity
    Coding is hard! (At least it is for the writer of this style guide). When you’re writing technical tutorials, ensure that the reader knows what step of the journey they’re on, what they need to do in that step, and what the next one is, with a clear bead on their ultimate goal of getting the app to production.

Keep your lede short

The highest reader engagement is at the top of the fold on a webpage - meaning your intro. On average, a user spends 15 seconds reading. They comprehend 30 words during that time. Keep your intros on blog posts.

Before the 30 word treatment:

In this blog post, we are going to use a functional approach to creating a web application with Erlang and the Chicago Boss framework. Our application will display incoming SMS messages in real-time and allow you to respond to them in your browser using the Twilio API.

After the 30 word treatment:

Put down your phone. Using Erlang, Twilio and the Chicago Boss framework, we’ll build a web app that displays incoming SMS in real-time and allows us to respond straight from the browser.

Write with opinion and empathy

You can ship a technical post that’s rock solid from a technical perspective, but doesn’t resonate with the reader. When you’re writing a technical tutorial, picture your reader in mind. Have a clear grasp on what they know, what they’re trying to build, and how you’ll get them there. You are the subject matter expert in this case - act like it. Write from the standpoint of trying to build a great experience for the user as they follow your expert opinion.

Do

Remember, don’t hard code your credentials into your Twilio app. This is a big security vulnerability. Storing critical account information as environmental variables is a much better way to keep you and your application safe.

Don't

Do not hardcoded credentials into your app. Researchers have determined this practice to be a security vulnerability. Please avoid this practice and protect your sensitive Twilio information in another way.

Write with a beginning, middle, and end

This seems obvious, but it’s hard to remember when you’re deep into a blog post. Outline your posts so you have a grasp on the proverbial beats of your post - what the reader should know in the introductory paragraphs, what they’re expected to accomplish in the middle paragraphs, and what they should celebrate at the finish line. As humans, we structure stories in this way and naturally look for a beginning, middle, and end as a framework to understand narrative. Use this narrative structure.

Website

No website on Twilio.com is an island. Every site on Twilio.com is part of a network of interlocking pages.

Collectively, these pages are some of the most valuable and visible places to deliver your message. Here’s how you do just that.

Disregard tribal knowledge

You might feel like some concepts are obvious. But, you’re likely an expert. You can’t assume the audience are all expert. You have to make clear statements using terminology anyone outside Twilio can understand. Don’t rely on insider terms or product names to point to a definition or product category.

Do

Build applications quickly using Twilio Studio, a simple drag-and-drop application platform.

Don't

Craft exceptional experiences with Twilio Studio, an easy way to build automated conversations with customers.

Deliver your message confidently and authentically

Twilio separates itself from the pack by communicating accurately and authentically, no matter the subject matter or audience.

You’re writing a website because you have something exceptional to share. Your job is to clearly communicate what that something is, how the reader should use it, and what value it offers them.

You can’t do this without having clearly organized and well-documented ideas, facts to back those ideas up, and a clear overarching narrative.

Consider the doors of information

Imagine you are apartment shopping. You open the front door to a new apartment and you step into the first room - the bathroom. There should definitely be a bathroom in the apartment. But, it shouldn’t be the first room in the apartment. This same principle applies to the information you share in a website.

Order your proverbial doors of information appropriately and with intent.

Start at door 1

Document who your reader is and what you expect them to know. This is the foundation of your website. It needs to be crystal clear and well documented before you move forward.

Then introduce the first, most basic concepts of the website. This is likely what your product is and what it does. If your reader doesn’t have a clear picture of what you’re writing about, you can’t move forward to features, value props, docs etc.

The next few doors

Just a friendly reminder that if you’re here, I assume your reader has a clear picture of what you’re writing about.

The next few topics you write about can get progressively more complex. But, you need to order your information sequentially so that if a reader gets lost, they can go back to the previous section for clarification.

Strong ties between sections not only help you produce a website your readers will understand, those ties will act as scaffolding for your messaging and narrative.

Don’t imitate your audience’s voice

It can be tempting to mirror the style and lexicon of your reader. It may seem like the easiest way to have your reader accept you as one of their own. In practice, you’ll do just the opposite.

If you’re imitating your reader without opinion or intention, you’re not offering anything new that is of value to your reader.

You are the subject matter expert who is building a website as a resource to your reader. That means you probably know what you’re talking about. That’s awesome! Use that voice - the empathetic expert - not the imitator.