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.
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.
Favor the imperative mood (giving commands) over declarative (making statements) in instructions.
Avoid using can in instructions unless you really mean to convey that the step is optional.
Don't include preceding articles (a, an, the) or surrounding punctuation in link text.
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.
Use an ordered list (numbers) when instructing the reader to perform a series of actions.
Use an unordered list (bullets) when breaking down sub-steps of an action.
Use an unordered list item for a standalone action.
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.
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 use ampersands unless one is part of a company or brand name.
Use the serial comma before the last item in a list.
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).
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.
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.
Titles and headings
Use sentence case for titles and headings.
Use imperative mood for titles and headings whenever possible.
UI elements and interaction
Bold the names of UI elements and Lighthouse audits.
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.
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.
Use pane to refer to the content areas associated with tabs—unless you're referring to an area in DevTools; then use panel.
Use KB for kilobytes, kb for kilobits.
Add a space before units.
To maintain a conversational tone, use common contractions.
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.
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.