How to write UI text

Checklist

For every CL that adds or changes UI texts in the Chrome DevTools front-end, use this checklist to make sure that the new or changed strings meet the basic requirements for good UX writing.

General

• Give the right info at the right time and place
• Don't write more than 1 sentence but if you do, break up text into sections, lists, tooltips, and Learn more links
• Be friendly but not ridiculous
  • ✔️ This API lets you collect data about what your users like.
  • ❌ Dude! This API is totally awesome!
  • ❌ This API may enable the acquisition of information pertaining to user preferences.

Patterns

• Follow the F pattern
• One sentence, one idea
• “To get what you want, do this”
  • ✔️ To save changes, drop a folder here
  • ❌ Drop in a folder to add to Workspace (what's a Workspace?)
• “Do this to recover”
  • ✔️ Shorten filename to 64 characters or less
  • ❌ Invalid filename

Mechanics

• Say “you”
• Look up short synonyms
  • ✔️ Keep, more, stop, get, send, add, fit, …
  • ❌ Preserve, additional, prevent, receive, submit, create, …
• Cut, cut, cut
  • ❌ Please, sorry, very, strongly, seamless, awesome, there is, there are, fast, quick, …
• Use active voice
  • ✔️ DevTools loaded source maps
  • ❌ Source maps were loaded by DevTools
• Use contractions but avoid Latin abbreviations
  • ✔️ Can’t, don’t, isn’t, for example, that is, and more
  • ❌ Cannot, do not, is not, e.g., i.e., etc.
• Use simple and common terms
  • ✔️ Website, page, extension, function
  • ❌ Debug target, debuggee, content script, call frame

Cosmetics

• Use sentence-case, not Title-Case (see Capitalization guidelines below).
  • ✔️ Periodic background sync
  • ❌ Periodic Background Sync
• Punctuate consistently
  • Use serial comma: A, B, and C
  • Skip periods in case of a single sentence
• Don't spell out numbers
  • ✔️ 1, 2, 3, …
  • ❌ One, two, three, …
• Use just 2 types of links: Learn more and the GM3 Help icon.

Capitalization guidelines

Capitalize product names

Capitalize product names, web API names, but not feature names.

• ✔️ Chrome DevTools (product) lets you debug Background Fetch API (web API) by logging background fetch (feature) events.
• ❌ Chrome devtools lets you debug background fetch API by logging Background Fetch events.

Use sentence case

Use sentence case in UI element names as well as titles and headings in text.

That is, capitalize only the first word in the title, the first word in a subheading after a colon, and any proper nouns or other terms that are always capitalized a certain way.

Examples: Network request blocking, Blocked response cookies

Spell UI elements in text

When mentioning UI elements in text, spell their names in bold and exactly as they are spelled, including capitalization, which should be in sentence case.

Example: Open the Network request blocking panel.

If an element doesn‘t have a name however, don’t capitalize its term and don't spell it in bold.

Example: A filter bar at the top of the Network panel, not the Filter bar.

Tip: You can “stack” navigation paths in text regardless of element type. For example:

In Settings > Preferences > Appearance > Panel layout, select auto.

That was [Panel] > [Tab] > [Section] > [Drop-down menu].

Resources

1. How to write UI texts (slides, recording)