Content Guidelines

House rules

CLARITY IS KING

  • Write for a grade 8 reading level. Reducing readability never means “dumbing down” your writing. It means communicating clearly and effectively, which if anything, is harder to do.
  • Use jargon thoughtfully. Yes, some of our users are tech-savvy, but not everyone has the same understanding of even the simplest technical jargon. Saying “component instance” might make sense in an advanced tooltip, but not in the general verbiage. 

READABILITY IS QUEEN

  • Stay concise. If you need to be wordy, break it up with subheadings, numbers, bullet points, and smaller paragraphs. The more digestible your content is, the more likely it is to be read.
  • Make the most of your headlines. They should clearly convey the main point, so anyone can scan just the headings for a summary. 

WHEN IN DOUBT, STICK TO AP STYLE

  • We use the AP Stylebook. Any exceptions mentioned here override AP. 
  • Merriam-Webster’s Collegiate Dictionary is our preferred source of truth, and we use American spelling, not British. The first listed spelling is our go-to. 

Capitalization

Avoid the urge to turn everything into a proper noun. Unexpected capitalization is distracting, so make sure that noun really deserves its own identity. 

TYPES OF COPY

  • Headlines, page titles, and navigation items are written in sentence case. That means you capitalize only the first word and any proper nouns. 
  • If a line of UX copy starts with a numeral, the numeral counts as the first word. No need to capitalize the word after it. 
  • YES: 1 unread, 3 more comments
  • ✗ NO: 1 Unread, Three more comments
  • When using the title case, follow AP Style. 
  • Never capitalize prepositions, conjunctions, or articles with four or fewer letters (the, a, an, of, or, but, for, from, with, etc.)
  • Capitalize all words with five or more letters (about, above, etc.)
  • If you find yourself needing to write in title case, double-check it on TitleCase.

Punctuation

EXCLAMATION POINTS (!!!)

  • Use exclamation points rarely and wisely. Keep in mind that, when used incorrectly, it can come off as though we’re laughing at our own joke. Avoid using more than one per send unless it’s really necessary.

EM DASHES (—)

  • Em dashes should be used intentionally. They create slightly longer, more dramatic pauses than commas, and should not be used as a substitute for a complete set of sentences. They don’t need to be as rare as exclamation points, but fall in the same family. 
  • When you do use them, do not put a space on either side. (We break with AP Style here.)
  • Insert an actual em dash (—), not — or -. The keyboard shortcut for an em dash on a Mac is shift-option-hyphen. 

EN DASHES (–)

  • Only use en dashes within a numerical range. For example, “10–15 seats” or “15–20 minutes.” 

ELLIPSES (…)

  • Ellipses are used very rarely, almost never. The most common use case is when a section of a quote is removed. 
  • Don’t use them at the end of search bar placeholder text, or as replacements for a complete thought. 
  • If you do need to use an ellipsis, do not add a space on either side of the three dots, or in between each dot. The keyboard shortcut for an ellipsis is opt-;.
  • When referring to the ‘More’ menu in an InVision dashboard, use “•••” by tapping Option+8 three times, instead of making an ellipsis.

COLON (:)

  • Capitalize the first word after a colon, if the phrase after the colon is a complete sentence.

AMPERSAND (&)

  • Don’t use an ampersand in place of “and,” unless required by space constraints. They tend to attract the majority of your audience’s attention to the least important word (“and”). 
  • If required by space constraints (especially in CTAs), use an ampersand (&) instead of a plus sign (+). 

QUOTATION MARKS (“)

  • When quoting something within another quotation, use single quotes within the double quotation marks. 
  • When quoting a thought, format it in italics instead of enclosing it in quotation marks.
  • For the blog and PR we use single quotes in headlines (The typography of ‘Stranger Things’), and regular quotes within the post (never single quotes).

COMMAS (,)

  • Whether you call it a serial comma or the Oxford comma, yes, we use it. 

Formatting

BOLD, ITALICS, UNDERLINE

  • When giving instructions, bold the tab the user is interacting with. If you’re referring to a tab within the product, mimic the capitalization used in the product. Capitalize, but don’t bold, keys.
  • YES: Hold Command-Cto copy text. 
  • YES: Select the Navigation tab.
  • ✗ NO: Hold the command key and C to copy text. 
  • Italicize album names, book titles, newspaper names, magazines, video games, movies, TV and radio shows, works of art, and published reports.
  • Add quotes around song titles, TV-show episode titles, poems, short stories, and individual music videos. 

LISTS

  • When you create a bulleted or numbered list, prioritize consistency. 
  • Start each line with the same word type, most likely a verb. 
  • Always capitalize the first word on each line.
  • If one line has ending punctuation, every line should. 

LINKING

  • Avoid adding the word “here” and linking from it (“Click here”). 
  • Whenever possible, hyperlink a full, actionable phrase that starts with a verb and describes the endpoint (“See the full list”). 

URLs

  • If you’re not using a CTA button, use a hyperlink whenever possible. Avoid typing out URLs.
  • On printed material, remove “http://www.” and solely include the domain. 

Abbreviation and acronyms

ADDRESSES

  • If you’re spelling out the entire street address, abbreviate the type of road. If you’re only referring to the street name, do not abbreviate. 
  • YES: 123 Main St.
  • ✗ NO: Sesame St. 

ACRONYMS

  • For uncommon acronyms and abbreviations, always spell them out upon first use. 
  • YES: Design System Manager (DSM)
  • ✗ NO: Introducing DSM
  • As per AP Style, do not use periods for acronyms, especially when using country abbreviations. “P.S.” is the exception. 
  • YES: USA, SF, P.S.
  • ✗ NO: U.S.A., S.F., ps
  • Abbreviations that end in a lowercase letter do periods.
  • YES: a.k.a., etc. 
  • ✗ NO: AKA, EG
  • Spell out words whenever space permits (like “organization”). Avoid shortening to things like “org” unnecessarily. 

CONTRACTIONS

  • Contractions are used to set a light, human tone. They’re welcome, as long as they sound natural when said out loud. 
  • YES: You’re all set up
  • ✗ NO: That’ll make sure you are all set up

Locations

STATE REGIONS

  • Lowercase the compass point, unless it’s a universally known region. 
  • YES: I’m moving from coastal Florida to Southern California.
  • ✗ NO: The event is in Northern Delaware. 

SPELLING OUT STATES

  • Spell out the full state name whenever space permits. (“We visited Clark in New York.”)

Numbers and percentages

NUMERALS

  • In headlines, subject lines, and text messages, always use the numeral. 
  • When not in a headline or subject line:
  • Always spell out the number when it’s the first word of a sentence. 
  • Spell out all numbers zero through nine. Ten and up, write out numerically.
  • For figures bigger than 999,999, write out the descriptor instead of listing zeroes. 
  • YES: 15 million, half a billion
  • ✗ NO: 15,000,000; 1/2 a billion

FRACTIONS

  • Spell out simple fractions. 
  • Hyphenate the fraction when it’s used as a modifier. 
  • YES: one third, four fifths, two-thirds of a pizza
  • ✗ NO: 1/3, four-fifths, two thirds of a pizza

MONEY

  • Always use numerals for amounts, except for “a dollar” when it reads more naturally than “$1” in context. 
  • Don’t capitalize types of currency. 
  • YES: $20, $3.25, euro
  • ✗ NO: three dollars and twenty-five cents, Euro

PHONE NUMBERS

  • As per AP Style, we use hyphens only: xxx-xxx-xxxx

PERCENTAGES

  • Never spell out “percent.” Always use the % symbol and a numeral.
  • When referring to “99.999% uptime,” include all three 9s after the decimal.

Dates and times

ABBREVIATING MONTHS

  • As per AP Style, we abbreviate months with more than five letters (Jan., Feb., Aug., Sept., Oct., Nov. and Dec.) when included in a date. 
  • If spelling out a full date provides more clarity (especially in Support documentation), go for it!
  • To help reduce noise, do not use a period after the abbreviated month for in-product commenting only. 
  • YES: Feb 27, 2018 at 10:30 AM
  • ✗ NO: Feb. 27, 2018 at 10:30 AM
  • When referring to vaguer dates, spell out the month. 
  • YES: February 2020
  • ✗ NO: Feb. 2020
  • Write out the month (instead of solely relying on numerals) whenever possible. 
  • YES: Feb. 27
  • ✗ NO: 2/27
  • If your audience is entirely outside of the US, format the date according to local standards. 
  • YES: Amsterdam’s Studio event is at 13:00 on 27 February 2018.
  • ✗ NO: Amsterdam’s Studio event is at 1 PM on February 27, 2018. 

AM/PM

  • Stick with all-caps “AM” or “PM” with a space between the number and AM/PM, and no periods. 
  • Never include :00 for times on the hour. 
  • YES: 8 AM, 10:21 PM
  • ✗ NO: 8:00 AM, 8AM, 10:21 pm, 9 a.m.

‘TH’ AND ‘ST’

  • Never follow numerical dates with “th” or “st,” unless you’re referring to a century. 
  • YES: The 21st century
  • ✗ NO: Feb. 27th

TIME PERIODS

  • In the product, when specifying how recently an update was made, always use the numeral. 
  • Write out the time measurement whenever space permits. 
  • YES: Edited 2 minutes ago, 1 hour ago, 1 month ago
  • ✗ NO: Edited two minutes ago
  • When short on space, abbreviate to the first letter of the measurement, with no space between the numeral and letter, and no periods.
  • YES: Opened 27m ago, 1h ago, 5mo ago
  • ✗ NO: Opened 1 h ago, 27 min ago
  • Round up to a clean unit of measure. 
  • YES: 50 minutes ago, 23 hours ago, yesterday, 3 days ago, 2 weeks ago, 7 months ago, 1 year ago
  • ✗ NO: 49 minutes and 35 seconds ago, 1.5 days ago, 2 days and 23 hours ago

YEARS

  • Apostrophes always replace what’s missing. 
  • YES: ’90s
  • ✗ NO: 90’s

Accessibility

  • Keep colorblindness in mind. Remember, 8–12% of men and .5% of women are color deficient.
  • Avoid giving direction only by color (“Click the red button to save.”)
  • Encourage collaborators to test their designs to make sure they’re high-contrast enough. 
  • When working on website or product copy, include alternative text (alt text) to help vision-impaired people navigate. 
  • Screen readers read alt text to describe the images to people who can’t see them, or if the image isn’t downloaded due to an iffy connection. 
  • In name fields, ask for the user’s “Full Name” instead of splitting it into “First” and “Last” whenever possible. This way, the form is easier to use and easily adaptable to all name structures.