UNPKG

chrome-devtools-frontend

Version:
121 lines (89 loc) 4.85 kB
# 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))