Product style guide

Core principles, punctuation, grammar and formatting in Product content.


Edit this page on GitHub

Content principles#

Identify your user and speak directly to them#

  • 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.

Write for the reading level of a 10-13 year old#

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

Using readability tools

Sites offering free readability tools like this one can be useful for assessing the "reading age" of long content (more than 150 words). However, they're not great at testing short UI content that might only contain two or three words. Use them with caution. Look for a simpler word whenever you can to improve the readability of your content.

Be inclusive of people and devices#

  • 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 the dropdown menu. Name the component or area you’re referencing.

Write as if the user is in a rush#

  • 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 scan for what they need.

Be direct and straightforward#

  • 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 company/industry jargon, idioms, or cultural references to communicate what you mean.
  • Use the words that are most familiar to the user.

It’s ok to bend grammatical rules to sound natural#

  • 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.

Exception: avoid contractions in error messages

Avoid contractions in negative scenarios. When a user is stressed, their comprehension suffers. Often users will read can’t as can, missing the -’t at the end. Write out error messages or destructive action warnings in full.

Punctuation#

Ampersands &#

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.

Why?

Using "and" rather than the ampersand symbol (&) supports localization and users with lower literacy or cognitive impairments. Some screen readers can’t interpret the code behind an ampersand, which obscures the meaning for the user.


Apostrophes '#

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.


Commas ,#

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.

Exclamation marks !#

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.

Parentheses ( )#

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."

Periods .#

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 it is the last line on an alert or notification.


Quotation marks " "#

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.


Semicolons ;#

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

Grammar and formatting#

Abbreviations#

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.


Acronyms#

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."

American English#

Do use American English spellings throughout products.

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

Bold and italics#

Bold#

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.
Italics#

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.

Capitalization#

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.

Currency#

Coming in a later release


Dates#

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.


I/You/We/Us#

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.)

Legal content

Legal content follows different rules to product — e.g., in Terms of Service, Twilio is usually referenced in the third person. Always check with the legal team if the content regards consent. If they suggest you use specific wording, use the wording the legal team suggests.

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.

Lists (all)#

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 "..."

Lists (bullet points)#

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

Lists (numbered)#

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.

Lists (sentence)#

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.

Numbers#

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.


Sentence case#

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.)

Time#

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
Absolute and relative time#

Coming in a later release

  • Time span
  • Ongoing time

Common errors#

e.g./i.e.#

  • 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/everyday#

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

It's/its#

  • 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/login#

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

Set up/setup#

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

Sign up/sign-up#

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

Their/there/they're#

  • Their = plural 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/that#

  • 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.

Support

If you need support, please open a new issue in our GitHub repository. Please try to provide as much detail as possible in your issue.

Contributing

The Paste design system is open source and contributions are welcome. Check out the project on GitHub to learn more about contributing.

Copyright © 2020 Twilio, Inc.