Product style guide

Keep the following principles in mind when writing product content. These mirror and complement the Twilio 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.

Write as if the user is in a rush. Avoid repetition and padding. Chunk content and use headings to help the user find what they need.

Be direct and straightforward. Front-load content with words that address the user’s needs and provide clear instructions for how to address that need. For example “To upload a CSV, select Upload.” Avoid jargon, idioms, or cultural references to communicate what you mean.

Write for the reading level of a 10-13 year old. Use simple, short sentences and common words. Explain technical terms.

Be inclusive of devices. Avoid instructing users to “click,” “tap,” or “touch” things in the UI. Tell them to “select” something instead.

Be inclusive of people. Avoid relying on directional or color-based cues, like “to the right” or “the blue button.” Instead, name the component you’re referencing. For example “Select Apply changes.”

It’s OK to bend grammatical rules to sound natural. For example, end sentences with prepositions or start a sentence with “But” or “And” if it sounds less awkward. Use contractions with pronouns — it’s, there’s, you’ll, we’ll, you’re — to sound conversational.

These style standards largely mirror the Twilio style guide, and provide product content-specific examples and rationale, where appropriate.

Use common abbreviations if space is limited, like in form labels.

In general, avoid abbreviations in body copy because it can lead to increased cognitive load and reduce comprehension. An exception to this rule is shortening “information” to “info,” as it is common.

Spell out the acronym the first time it is referred to, and then put the acronym in parentheses.

Use American English spelling.

Avoid using ampersands unless space is highly restricted or is part of a product/brand name.

Using “and” instead of an ampersand (&) helps localization and users with lower literacy or cognitive impairments. Also, some screen readers can’t interpret the code behind an ampersand.

Use bold type sparingly, to draw attention to the most important information the user needs to retain, and only if user testing indicates a need.

Bold UI elements when instructing the reader to interact with them. For example, “To review your order, select Continue.”

Capitalize proper nouns, including Twilio 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.

If another brand or product name uses a mix of upper and lower case (for example, eBay), use their formatting.

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

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

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

If it's absolutely necessary to cite a specific date numerically, use the ISO 8601 date format (YYYY-MM-DD), but consider which format is quickest to scan and easiest to read aloud.

Avoid repeating information. For example, if a log organizes its contents using Month YYYY (January 2020) sub-headings, the line items should only list the day (Wednesday 15).

Use a hyphen to indicate a date range.

Abbreviate months to their first 3 letters if space is limited.

Use a single exclamation mark to support a celebration. Never use more than one at a time.

Avoid using an exclamation mark to draw attention to an error message or alert. Exclamation marks can increase anxiety or be interpreted as shouting.

Use hyphens to create compound words, like “add-on”. Do not add a space on either side.

Use en-dashes to indicate a range of values like time, dates, and numerical amounts. Do not add a space on either side.

To create an en-dash:

• Mac: Option + - (hyphen)
• PC: Alt + 0150

Avoid using em-dashes in product copy. They are generally used to offset related information or highlight a break in a sentence. Instead, use short sentences.

• Speak directly to the user and address them as “you”.
• Refer to Twilio as “we” instead of “Twilio”, unless there is confusion about who “we” would refer to.
• It’s OK to use the possessive “our” when referring to Twilio.
• It’s OK to use “Twilio” as a noun when referring to the product, or as required by legal.
• Reserve using “I” for legal content (for example “I understand”).

Avoid using italic type wherever possible in product content.

• To draw attention to a word, bold it.
• If you need to quote a phrase, use quotation marks.

Start each list item with the same part of speech to make the list “parallel.”

Use periods at the end of each list item only when it’s a full sentence.

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

Lists contained within sentences can be hard to digest in product content. Consider using bullets to improve scannability.

Use precise numbers to express statistics, metrics, or quantities.

Use numerals in most cases (sometimes it just looks wrong!). They’re often easier to comprehend in product and require fewer characters.

Write out ordinal numbers. For example, “third” instead of “3rd.”

Use commas in values greater than 999.

Use both words and numerals for numbers over 1,000. For example, “SendGrid sent over 40K emails.”

Use a space between the number and its unit of measurement. For example, “40 GB” or “More than $1.3 billion.”

Be consistent, even if it means overriding the general rule. For example, “This article has 16 pages, another has 7 pages, and a third has only 5 pages.”

Use parentheses to provide an example, explanation, or to note an acronym. Do not use parentheses for whole sentences.

End every full sentence with a period.

Don't use periods in headings.

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 of a piece of content.

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

Place commas and periods inside the quotation marks.

Don't use quotation marks to refer to products or features.

Avoid using semicolons. They’re too formal for product content. Use two sentences instead. Or simplify the sentence.

Use sentence case everywhere, even in H1s, CTAs, and navigation. It feels more human, and is easier to read.

Use the “hour:minute” format. For example, “4:15. Use the 12-hour clock with a.m./p.m. modifiers. When necessary, add the time zone after the time.

Reserve for links. To draw attention to very important information the user needs to retain, use bold instead.