Style Guide

Usage and grammar

• Acronyms. Try not to use them. If you must, provide a definition when you first use one.
• Contractions. Use them whenever they won’t sacrifice clarity. They generally make copy sound more conversational.
• Em dashes. Format them with a space on each side — like this. To a browser’s line-breaker, word—word is a single unbreakable token, which can force awkward overflow at narrow widths. Spaces give the line-breaker somewhere to wrap.
• En dashes. Use to denote a range, such as October 7–9.
• Jargon. Speak plainly and avoid jargon as much as possible.
• Numbers. Spell out numbers one through ten. Write higher numbers as digits. For example: use 13, not thirteen. Two exceptions: technical specifications take digits (“8 characters minimum,” not “eight characters minimum”), and related numbers share a format (“one was 8 and the other 13,” not “one was eight and the other 13”).
• Oxford or serial comma. Use it here, here, and here.
• Their. Use it as a gender-neutral possessive pronoun.
• They. Use it as a gender-neutral pronoun to refer to multiple people or just one. For example, “They rode their bike to lunch.” and “They rode their bikes to lunch.” are both correct. (It’s also good to use words like folks or y’all to address groups of people instead of using the gender-specific guys.)
• Your (not my) is the possessive pronoun we use to describe features or items that belong to a user.

Website guidelines

• Use sentence case for all headers and button copy.
• Use ampersands in headings when space is tight. Otherwise, just use the word and.
• Use title case only for titles (e.g., the title of a blog post or newsletter).
• Don’t use terminal punctuation in headers or titles, unless you need a question mark or exclamation point. And if the latter, you probably don’t. The exception: a header that runs to more than one sentence — where the punctuation between sentences forces the issue, and the final one should terminate too.
• Don’t link terminal punctuation.
• Ensure linked text describes the result of clicking the link. Ideally, linked text meant to prompt action appears at the end of a sentence, so the reader can take action as soon as they understand the task.

Word list

Adapted and extended from the O’Reilly Style Guide, our favorite reference for many years.