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
- Click Remix to Edit to make the project editable.
- Click Terminal (note: if the Terminal button does not show you may need to use the Fullscreen option).
Use an unordered list (bullets) when breaking down sub-steps of an action.
Good
- 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
.
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 
.
Do
Click Fullscreen .
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.
Use about:// instead of chrome:// for built-in URLs in web.dev articles. This generalizes these URLs to all Chromium forks. Typing about:// in such a browser will be rewritten to a browser-specific scheme. For example typing about:// in Microsoft Edge will be rewritten to edge://. For more background on this rule, see the article How to set browser flags in Chromium.
Don't
chrome://
Do
about://
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!
- The Google Developer Documentation Style Guide (GDDSG) is the primary reference for writing style issues.
- If a style issue isn't covered in the GDDGS, check the Chicago Manual of Style.
- Merriam-Webster is the primary reference for spelling and capitalization.
- The Word list provides spelling and capitalization conventions specific to web.dev.