chrome-devtools-frontend
Version:
Chrome DevTools UI
121 lines (89 loc) • 4.85 kB
Markdown
# How to write UI text
[TOC]
## 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 <u>Learn more</u> 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](https://m3.material.io/foundations/content-design/style-guide/ux-writing-best-practices#3a833840-43db-4f6e-8133-c4665c17d176)
* 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](https://translate.google.com) 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](https://developers.google.com/style/contractions) but avoid [Latin abbreviations](https://m3.material.io/foundations/content-design/style-guide/ux-writing-best-practices#98d02949-1933-49df-b136-f7b72620b950)
* ✔️ `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](#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: <u>Learn more</u> and the
[GM3 `Help` icon](https://fonts.corp.google.com/icons?selected=Google+Symbols:help).
## Capitalization guidelines
### Capitalize product names
Capitalize [product names](https://developers.google.com/style/product-names#capitalize),
web API names, but not [feature names](https://developers.google.com/style/product-names#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](https://m3.material.io/foundations/content-design/style-guide/ux-writing-best-practices#fc5c2a78-f4bf-4d42-bdac-42ff80391129) as well as [titles and headings in text](https://developers.google.com/style/capitalization#capitalization-in-titles-and-headings).
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.
*** aside
Examples: **Network request blocking**, **Blocked response cookies**
***
### Spell UI elements in text
When mentioning [UI elements in text](https://developers.google.com/style/ui-elements#formatting),
spell their names in bold and exactly as they are spelled, including
capitalization, which should be in sentence case.
*** aside
Example: Open the **Network request blocking** panel.
***
If an element doesn't have a
name however, <em>don't</em> capitalize its term and <em>don't</em> spell it in
bold.
*** aside
Example: A filter bar at the top of the **Network** panel, not ~~the **Filter** bar~~.
***
*** note
**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](https://docs.google.com/presentation/d/1AfsX0JaMd1iBNH1WL2dMswXLuhGSU5j2cyAEHkJpoNA?resourcekey=0-cfKK72Q_tV8-uakhzuVx-g),
[recording](https://drive.google.com/file/d/19wOnbZHvXhH-tQLuE0M2B9fQMjosLC9O?resourcekey=0-FBrvUvnWMq0Wa98vkea9-A))