Grammar, mechanics, and usage

Grammar, mechanics, and usage

Grammar and mechanics are important for making writing clear, but don't let them get in the way of putting text on the page! Content reviewers will always support you with editorial stuff. That said, here are a few conventions to be aware of.

Instructions

Use second person (you) rather than first person (we) except in rare cases where you're providing a rationale for a recommendation (e.g., "We chose this library because…").

Begin instructions with the objective rather than the action.

Don't

Drag a photo to the trash to remove it from an album.

Do

To remove a photo from an album, drag it to the trash.

Favor the imperative mood (giving commands) over declarative (making statements) in instructions.

Don't

You will click Run Audit.

Do

Click Run Audit.

Avoid using can in instructions unless you really mean to convey that the step is optional.

Linking

Don't include preceding articles (a, an, the) or surrounding punctuation in link text.

Don't

See the "Easily discoverable" collection for more information.

Do

See the Easily discoverable collection for more information.

When referring to webpages, either on web.dev or elsewhere, hyperlink the webpage title only, without quotation marks. (See example above.)

Libraries and tools should be linked the first time they're mentioned.

Lists

Use an ordered list (numbers) when instructing the reader to perform a series of actions.

Good

  1. Click Remix to Edit to make the project editable.
  2. Click Tools.
  3. Click Logs.
  4. Click Console.

Use an unordered list (bullets) when breaking down sub-steps of an action.

Good

  1. Do the hokey pokey:
    • Put your left foot in.
    • Take your left foot out.
    • Put your left foot in and shake it all about.

Use an unordered list item for a standalone action.

Good

  • To preview the site, press View App. Then press Fullscreen fullscreen.

Numbers

In general, spell out integers from one to nine unless:

  • The integer is attached to a unit (e.g., 3 KB, page 3).
  • The integer is in the same sentence as a number larger than nine (e.g., "The menu contains 15 options, but 6 of them are disabled.")

Use numerals for decimals and numbers higher than nine.

Pronouns

Avoid ambiguous pronouns. Follow the advice on the GDDSC Pronouns page. Also avoid pronouns that refer to clauses or phrases, which can complicate translation into some languages.

Don't

Speed optimizations often regress quickly. Performance budgets are one way to address this.

Do

Speed optimizations often regress quickly. Performance budgets are one way to address this problem.

Punctuation

Ampersands

Don't use ampersands unless one is part of a company or brand name.

Don't

Safe & secure

Do

Safe and secure

Commas

Use the serial comma before the last item in a list.

Don't

React, Vue and Angular are popular frameworks.

Do

React, Vue, and Angular are popular frameworks.

Dashes and hyphens

Use hyphens (-) with no surrounding space to link words together (e.g., two-year-old).

Use em dashes (—) with no surrounding space—like this—to set off an aside.

Use an en dash (–) for ranges (e.g., 10–100 KB).

Quotation marks and apostrophes

Use straight quotation marks and apostrophes, not smart (curly).

Don't

The "Accessible to all" collection

Do

The "Accessible to all" collection

Periods and commas always go inside quotation marks. Question marks and exclamation points go inside quotation marks if they're part of the quotation; outside if not.

Don't

Jane said, "Reader, I married him".

Do

Jane said, "Reader, I married him."

Text formatting

Bold words for emphasis sparingly. (The primary use for bolding is indicating UI element names.)

Avoid mixing code font and standard font in a single word.

Don't

integers

Do

integer values

Titles and headings

Use sentence case for titles and headings.

Don't

Optimize Your Images

Do

Optimize your images

Use imperative mood for titles and headings whenever possible.

Don't

Optimizing your images

Do

Optimize your images

UI elements and interaction

Bold the names of UI elements and Lighthouse audits.

Don't

In the New Project window, select the "New Activity" checkbox, and then click "Next."

Do

In the New Project window, select the New Activity checkbox, and then click Next.

Do

To find slow third-party scripts, check the Reduce JavaScript execution time and Avoid enormous network payloads audits in the Diagnostics section.

When referring to a button with an icon but no label, use the name of the button as shown in the tooltip, and add the button icon immediately after. Don't style the icon unless the button would be difficult to recognize without its original styling.

Don't

Click Fullscreen icon.

Do

Click Fullscreen Fullscreen icon.

To refer to a keyboard key:

  • Use the key's name in code font.
  • Spell out the names of modifier keys.
  • To refer to a key combination, use the form Modifier+Key (no spaces).
  • When the reader may be on either Windows or Mac, put the Mac shortcut in parentheses after the Windows shortcut.

Don't

To copy, press Ctrl + C (⌘ + C).

Do

To copy, press Control+C (or Command+C on Mac).

Use pane to refer to the content areas associated with tabs—unless you're referring to an area in DevTools; then use panel.

Units

Use KB for kilobytes, kb for kilobits.

Add a space before units.

Don't

100KB

Do

100 KB

Usage

To maintain a conversational tone, use common contractions.

Don't

This collection assumes that you are already familiar with Angular.

Do

This collection assumes that you're already familiar with Angular.

Use consistent vocabulary throughout a piece and the collection it lives in.

Acronyms should be spelled out the first time they're used, with the acronym following immediately after in parentheses.

Don't

WICG

Do

Web Incubation Community Groups (WICG)

References

These are the references content reviewers use when reviewing posts and codelabs for editorial issues beyond the ones covered in this post. They worry about this stuff so you don't have to!

Last updated: Improve article