Product style guide

• Consider who you're writing for and their technical level. Use words the user is familiar with.
• Address the user as you, refer to Twilio as we.

• Use simple, short sentences and common words.
• Explain technical terms and write acronyms in full the first time a user sees them.

• Avoid click, tap, touch instructions as not every device supports touch.
• Instead, use select to instruct a user to interact.
• Avoid relying on directional or color-based cues — to the right, the blue button. These are problematic for responsive products or users who see colors differently.
• Instead, write the main menu or select "Apply changes". Name the component or area you’re referencing.

• Avoid repetition and padding.
• Phrases we use when writing formally or presenting — please note, so, in fact, in other words — should be cut.
• Chunk content and use headings to help the user find what they need.

• Lead with the reason (why), by front-loading messages with words that address the user’s needs.
• Leave the user with a clear instruction of how to address that need.
• Avoid relying on Twilio or industry jargon, idioms, or cultural references to communicate what you mean.
• Use the words that are most familiar to the user.

• End sentences with prepositions — of, with, for — if it sounds less awkward.
• And you can start sentences with But or And.
• Use contractions with pronouns — it’s, there’s, you’ll, we’ll, you’re — to sound conversational.

Avoid using ampersands. In exceptional circumstances, if space is unavoidably restricted or it's part of a product/brand name, use "&".

Do use "and" instead of an ampersand (&).

• Voice and messaging
• Create and submit a Regulatory Bundle.
• Messages sent from AT&T to Twilio numbers are not impacted.

Don't use "&" just to make content shorter. If space is an issue, address the content and design together.

Do use an apostrophe to indicate possession or belonging.

• The APIs of Twilio > Twilio's APIs
  • The phone number's prefix.
  • Choose from one of SendGrid's responsive email designs.

Do use an apostrophe to indicate missing letters.

• You are > you're
  • You're not logged in.

Don't use apostrophes to make a plural. We should never see Upgrade to buy phone number's, Install plugin's, or SID's.

Do use the serial or 'Oxford' comma in a list of 3 or more items.

• You can customize the agent desktop, channels, interaction routing, and reporting.

Do use a single exclamation mark to support a celebration. But never more than one at a time (!!)

• Congratulations, you sent your first email!

Don't use exclamation marks to draw attention to or emphasise an error message or alert. Exclamation marks can increase anxiety or sound like shouting. Unless it's a clear moment of success, don't use them.

Hyphens and dashes - – —

Do use hyphens (-) to create compound words.

• Hyphens never have a space either side.
  • Add-on feature

Do use en-dashes (–) indicate a range of values (time, dates, numerical amounts.)

• En-dashes never have a space either side.
  • 0-50 agents
  • Tip: If your system does not support en-dashes, use a hyphen to indicate range.

Avoid using em-dashes (—) to create an emphatic pause.

• Tip: It's ok to write a very short sentence to emphasise its meaning. We might use em-dashes with friends and colleagues in email and chat to signify an added thought, but the user needs clarity over what's important. Give the thought a sentence or restructure your syntax.

Do use parentheses to provide an example or explanation.

• Password must contain a special character (&, @, %, \$, ^)

Do use parentheses to note an acronym the first time a user encounters it.

• Transport Layer Security (TLS) is a mechanism for securing your SIP connections.
  • In this example, the user is familiar with the term "SIP" but not "TLS."

Do end every full sentence with a period.

• Enable Flex Dialpad in Console.
• Sign up for a free account.

Don't use periods at the end of fragments or incomplete sentences.

Don't use periods at the end of an anchor link if it is the last line on an alert or notification.

Do use quotation marks to pick out words from a component or a file name.

• Select "Apply changes"
• We recommend using dedicated accounts for your development environments, like "Flex Production" and "Flex Development."

Do put punctuation inside quotation marks, if necessary.

• To create a new project, select "Create My Flex Project."

Don't use quotation marks to refer to products or features. Products and features are proper nouns and should be capitalized to differentiate them.

Avoid using semicolons. In formal writing, semicolons are useful. In product content, they can be messy and confusing.

• If you feel your sentence needs a semicolon, simplify it or create two sentences.

Do use punctuation and conjunctions (and, but, so) to separate thoughts.

• List complex items that already contain a comma using bullet points. For example, state capitals
  • Montgomery, Alabama
  • Juneau, Alaska
  • Phoenix, Arizona

Do use common abbreviations if space is limited, such as in form headings.

• Ref. in place of Reference
• No. or # in place of number
• Info in place of information

Do use a period at the end of the abbreviation if the last letter is not the same as the full word's last letter.

• Ref. in place of reference
• Info in place of information

Avoid using abbreviations in body copy. It might reduce the character count but it can increase cognitive load and reduce comprehension.

Do write the phrase in full, followed by the acronym in parentheses the first time a user encounters it.

• Transport Layer Security (TLS) is a mechanism for securing your SIP connections.
  • In this example, the user is familiar with the term "SIP" but not "TLS."

Do use American English spellings throughout products.

• Behavior, dialed, color, artifact, center, license (for both verb and noun), -ize endings, program (for all meanings)

Do use bold type sparingly, to draw attention to the most important word, number, or short phrase in your copy.

• Bold type can help a user scan the page more effectively by making landmarks more prominent.

Do consider using bold type to refer to UI elements in instructional content. E.g.

• Select the location from Region/State.
• Select Continue to review your order.

Don't use bold multiple times in body copy or for a whole sentence/paragraph. It dilutes its effect.

• Only bold the most important information the user needs to retain and only use it if user testing indicates a need.
• Consider if putting an important sentence on a new line will do a better job of making it stand out than making it bold.

Avoid using italic type wherever possible in product content.

• If you need to draw attention to a word, use bold type.
• If you need to quote a phrase, use quotation marks "like this."
• While you may see italics used elsewhere at Twilio, in products let's keep it simple and avoid it.

Do capitalize proper nouns – products, people, places.

• Products include features, programs, or systems that Twilio has given a specific name to.
• If a brand or product name uses a mix of upper and lower case (TwiML, eBay) use the name's convention.
• People are named individuals or identifiable roles.

Don't capitalize general terms (email, contact center, platform, phone number)

• Tip: If it's something Twilio has created or owns, it takes a capital.

Do write dates so that they are easy to scan and sound human to read aloud.

• Day, Month DD, YYYY (Sunday, May 17, 2020) — when referencing a specific day and the year is not clear from the context.
• Month DD, YYYY (May 17, 2020) — when the day of the week is unimportant or does not help the user scan.
• Month YYYY (May 2020) — when only the month is relevant. Useful in subheads to organize chronological lists.

Avoid repeating information. If a history or log organizes its contents using Month YYYY sub-headings, the following line items should use Day DD.

• For the subhead January 2020, the dates that follow would read Wednesday 15, Tuesday 28 and so on.

Do indicate a date range by using to between values.

• _January 24 to February 3, 2020
• January 24 to 28

Do abbreviate months to their first 3 letters if space is limited.

• Jan, Feb, Mar

• Tip: If it's absolutely necessary to cite a specific date numerically, use the ISO 8601 date format YYYY-MM-DD But note that this may not be useful to your user. Always consider which format is quickest to scan and easiest to read aloud.

Do refer to the user as you and to Twilio as we.

• Tip: If the user has agency or ownership, use ‘I’ or ‘my’.
  • If you still can’t connect, contact our support team.
  • To access billing information, select My Account.
  • I understand. (This usage is almost exclusively for legal consent.)

Do say we instead of Twilio

• It's us talking, so there's no need to refer to us in the third person.
• If "Twilio" is included in a product or feature name, that's ok as that's using it as a noun.

Do start each list item with the same part of speech – usually a noun or verb – to make the list "parallel."

• Punctuate the end of each item with a period if it is a complete sentence.
• Be consistent within the list. If one item takes a full point, all items should.

Don't punctuate the end of an item in a vertical list with a comma or ellipsis "..."

Do use bulleted lists for items linked by a topic. Make the list topic clear in the sentence or heading that precedes it.

Do use numbered lists for items to be done or understood in a sequence.

Avoid listing more than 7 items — it's a lot to take in. Break a big lists into smaller ones with explanatory headings.

Do use a sentence list if you’re explaining a short process, noting up to four options, or highlighting up to four key points. You just read a sentence list.

• Sentence lists should be used for no more than four items. Over four? List with bullet points.
• Use the Oxford comma before the last item in a sentence list.

Do use precise numbers to express statistics, metrics, or quantities. Avoid rounding up or down when the user is depending on the information to be accurate.

Do use numerals (1, 2, 3, 45, 101) instead of spelling out the number.

• Percentages 49%

Do write expressions that use ordinal numbers in words.

• One to watch, thousands of options
• First, create a profile

Do use both words and numerals to represent numbers over 1000, unless the user needs a specific number.

• Up to 40k emails
• More than $1.5B
• Note this is most commonly used in marketing content — make sure you're giving the user what they need to complete a task, and not overloading them with extra info.

Do use a space between the number and its unit of measurement or its order of magnitude if this is written out in words.

• 40 GB, 564 customers
• More than $1.3 billion, 45 million customers

Do use commas in numbers that are four or more digits.

• 1,365 messages sent

Don't use commas in error codes, account numbers, or phone numbers.

Do use sentence case everywhere, even in H1s, CTAs, and navigation. Sentence case makes content feel more human and it's generally easier to scan.

• This is sentence case. (Use this.)
• This is Title Case. (Rarely use this, and only if directed.)
• THIS IS ALL CAPS. (Don’t use this.)

Do write times so that they are easy to scan and sound human to read aloud. Usually, this means using the 12hr clock, with am/pm modifiers.

• 12:25am
• 3:32pm

• e.g. = for example
  • Create a memorable name for your Flex Project, e.g. "Flex Training 2020."
• i.e. = that is
  • Tip: i.e. usually precedes a simpler way of saying something. Say it simply the first time. Avoid writing i.e. if you can.

• Every day = each day
  • Twilio supports thousands of customers every day.
• Everyday = ordinary/usual
  • Twilio supports everyday customer needs, like call routing.

• It's = contraction of "it"+"is"
  • It's now possible to view real-time queue stats.
  • Tip: Can you say it is instead of the word you want? Does the sentence make sense? You want it's.
• Its = possessive pronoun (belonging to it)
  • The company and its customers.

• Log in = verb
  • To access your account, please log in.
• Login = noun/adjective
  • Enter your login details.

• Set up = verb
  • Set up your profile.
• Setup = noun/adjective
  • System setup information can be found in the user guide.

• Sign up = verb
  • Sign up for a free account.
• Sign-up = noun/adjective
  • Visit the sign-up page for more information.

• Their = plural and/or gender neutral possessive pronoun (belonging to them)
  • The main priority for agents is reducing their wrap-up time.
• There = adverb meaning existing in/at that place
  • There is a new version available.
• They're = contraction of "they"+"are"
  • Users are important. They're our top priority.

• Who = refers to people
  • Team leads who manage multiple business areas can use queues to assign tasks.
• That = refers to things
  • Companies that require security should enable Secure Media.