Our choice of which English to use depends on each client’s preference and house style. In the absence of a specified preference, default to American English.
Abbreviations, initialisms and acronyms
Don’t spell out common shortenings, like API or HTML.
Shortenings written in all caps take no points (API not A.P.I.) and are followed by a lowercase ‘s’ in plurals (APIs not API’s). Only use an apostrophe to indicate possession:
- ✅ Check the API’s documentation.
If there’s a chance your reader won’t be familiar with an acronym or initialism, spell it out the first time followed by the short version in brackets:
- ✅ Coordinated Universal Time (UTC)
Use the abbreviations “i.e.”, “e.g.” and “etc.” sparingly, but format them as written here if you do. If you’re unsure of the proper use of these shortenings, try using their definitions in their place to see if your sentence makes sense: i.e. “that is” e.g. “for example” etc. “and other things”
Don’t use an apostrophe to indicate plural forms.
Use an apostrophe to indicate missing letters (can’t is a contraction of cannot) or possession (Acme’s tool).
Possessive pronouns don’t take an apostrophe: hers, his, its, ours, theirs and yours.
Place inline code between backticks.
Use backticks to reference bits of code you’re narrating, but not for labels or button text.
- ❌ Enter the filename and click
- ✅ Import the built-in node
Avoid starting headings or sentences with backticks or code:
request.argsis an ImmutableMultiDict.
- ✅ The
request.argsattribute is an ImmutableMultiDict.
Use sentence capitalization for titles and headings rather than title capitalization, unless the client expresses a preference for title capitalization. If you’re unsure, check the client’s style guide (if they have one) or match formatting to their existing documentation.
- ✅ Using multiplayer with anonymous users
Title capitalization: Capitalize the first word of the title and all nouns, verbs, adjectives and adverbs. Don’t capitalize articles (a, the), prepositions (on, over), and conjunctions (and, but).
- ✅ Setting up Stripe Checkout and Email Subscription with Flask and Code Capsules
Some company names use irregular capitalization rules. We’ve compiled a list of common examples here, but you should check the company’s website to confirm their preferred formatting if there’s any doubt.
If a business’s website doesn’t clear up how to capitalize their brand name, follow Wikipedia’s usage.
Capitalize the names of websites and web publications. Don’t italicize.
Use a serial comma in lists:
- ✅ We shouldn't store passwords, access keys, personal information, or anything else sensitive in publicly accessible files.
Avoid comma splices:
A comma splice occurs when two independent clauses are joined with a comma:
- ❌ Download the files you need, unzip them on your computer.
A clause is independent if it can stand alone as a complete sentence.
Correct comma splices by rewriting the independent clauses as complete sentences:
- ✅ Download the files you need. Unzip them on your computer.
Alternatively, add a conjunction:
- ✅ Download the files you need, and unzip them on your computer.
Comma splices can be corrected by replacing the comma with a semicolon, but this approach is not recommended for our content:
- ✅ Download the files you need; unzip them on your computer.
Use common contractions (we’ll, let’s, can’t) to make your tone friendly and informal, but avoid less common contractions (d’ya know ’em?).
Use uppercase when referring to a file type, add a lowercase s without an apostrophe for plurals:
- ✅ PNG
- ✅ PDFs
Specific file names should be in lowercase: * ✅ tictactoe.png
Avoid using italics for emphasis.
Avoid numbered lists.
Fractions and decimals
Spell out and hyphenate fractions: two-thirds (not 2/3 or two thirds).
Use decimal points when a number is not easily written out as a fraction: 1.273.
Login, log in, log in to
Your access credentials:
* ✅ Keep your login details handy.
log in (phrasal verb)
* ✅ To make these changes, you'll need to log in.
log in to
The term "log in" is a phrasal verb, so we add the preposition after a space:
* ✅ Log in to GitHub.
Spell out a number when it starts a sentence or if it's under ten, otherwise use numerals:
- ✅ Nine elements make up the array.
- ✅ The array has nine elements.
- ✅ MetaMask will give you a 12-word secret recovery phrase.
Some common expressions work best with numbers spelled out:
- ✅ Back to square one.
- ✅ An all-in-one solution.
Ordinals should mostly be avoided, but spelled out when used:
- ✅ Third-party
- ✅ First impression
Numbers over three digits get commas
- ✅ 999
- ✅ 1,000
- ✅ 3,500,000
Use the % symbol instead of spelling out “percent”.
Use they, their and them in the singular if the subject’s gender is unknown or irrelevant:
- ✅ Send your collaborator the join link and they'll be redirected to the sign in page.
Never use the pronoun “one”.
Refer to a company or product as “it” (not “they” or “them”):
- ✅ Replit is an online IDE. It has various collaborative features.
Use double quotation marks to identify labels or button text:
- ✅ Click “OK” to complete set up
Setup vs set up
We use setup as a noun or adjective:
* ✅ A microservices setup. * ✅ Follow the setup instructions.
We use set up as a verb: * ✅ How to set up your account.
URLs and websites
Avoid spelling out URLs, but when you need to, leave off the http://www.