Skip to content

Grammar

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”

Apostrophe

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.

Backticks

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 OK.
  • ✅ Import the built-in node http package.

Avoid starting headings or sentences with backticks or code:

  • request.args is an ImmutableMultiDict.
  • ✅ The request.args attribute is an ImmutableMultiDict.

Capitalization

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.

Commas

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.

Contractions

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

File extensions

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

Formatting

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

login (noun)
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.

Numbers

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

Percent

Use the % symbol instead of spelling out “percent”.

Pronouns

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.

Quotation marks

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.