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 (the user's password).

Possessive pronouns don't take an apostrophe: hers, his, its, ours, theirs, and yours.

Avoid using a possessive apostrophe with brand names and inanimate things:

❌ Speakeasy's SDK Generator.
✅ The Speakeasy SDK Generator.
❌ The applications's administrator.
✅ The administrator of the application.

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

Titles and headings

Capitalize titles and headings according to the customer's style guide if they have one or match capitalization to their existing documentation.

At Ritza, we default to sentence case for titles and headings.

✅ Using multiplayer with anonymous users

Some of our customers prefer title case for titles and headings.

Title case uses an initial capital for the first word of the title and all nouns, verbs, adjectives, and adverbs. Don't capitalize the first letter of articles (a, the), conjunctions (and, but), and short prepositions (on, for). Applying title case can be tricky because a word may have a different function depending on its context. For example, "to" is a preposition in "Migrating to Bryntum" but an infinitive marker (part of the verb) in "How To Log In".

To correctly capitalize titles and headings, use a tool like Title Case Converter.

✅ Setting Up Stripe Checkout and Email Subscription With Flask and Code Capsules

Occasionally, our customers prefer start case for titles and headings. Start case uses an initial capital for every word.

✅ Using The FusionAuth React SDK In A React Application

Company names

Some company names use irregular capitalization rules. We've compiled a list of common examples here, but you should check the company website to confirm their preferred formatting if there's any doubt.

If the company website doesn't clear up how to capitalize their brand name, follow Wikipedia usage.

Websites and web publications

Capitalize the names of websites and web publications. Don't italicize.

Code comments

When adding comments to your code, start with a capital letter and use conventional punctuation if the comment is a full sentence or multiple sentences.

✅ // This config enables response validation and dumping of found errors to the browser console. It's meant to be used as a helper during the development stage, so please set it to false for production systems.

Short phrases and incomplete sentences don't need to start with a capital letter or end with a period.

✅ // insert record

Commas

Use a serial comma in lists:

✅ We shouldn't store passwords, access keys, personal information, or anything else sensitive in publicly accessible files.

Use a comma to separate introductory words, phrases, or clauses from the main clause of a sentence. These include:

Transitional phrases and words
- ✅ However, to ensure data security, it's crucial that you now set up appropriate user permissions.
Adverbial phrases and clauses
- ✅ In reality, you'll want to create a random user at the beginning of each login test.
Conditional phrases and clauses
- ✅ Before you can write any tests, you need a test user profile to log in with.

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

In file names, extensions should be 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 (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 http://www..