page.title=Writing Style
page.tags="dialog","toast","notification"
@jd:body
<h2 id="voa">Android's Voice</h2>
<p>When writing text that appears in your app, keep it concise, simple, and friendly.</p>
<h4 id="concise">Concise</h4>
<ul>
<li>Describe only what the user needs to know.</li>
<li>Eliminate redundancy, such as titles that restate the body of an information box.</li>
<li>Keep text as short as possible.</li>
</ul>
<p><em>Avoid wordy, stilted text</em></p>
<div class="layout-content-row">
<div class="layout-content-col span-6 layout-with-list-item-margins">
<div class="do-dont-label bad">Don't</div>
<table class="ui-table good"><tbody><tr><td>
Consult the documentation that came with your phone for further instructions.
</td></tr></tbody></table>
</div>
<div class="layout-content-col span-6">
<div class="do-dont-label good">Do</div>
<table class="ui-table good"><tbody><tr><td>
Read the instructions that came with your phone.
</td></tr></tbody></table>
</div>
</div>
<p><em>Don't provide unnecessary information</em></p>
<div class="layout-content-row">
<div class="layout-content-col span-6 layout-with-list-item-margins">
<div class="do-dont-label bad">From a Setup Wizard screen</div>
<table class="ui-table bad">
<thead>
<tr>
<th>
Signing in...
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
Your phone needs to communicate with<br>
Google servers to sign in to your account.<br>
This may take up to five minutes.
</td>
</tr>
</tbody>
</table>
</div>
<div class="layout-content-col span-6">
<div class="do-dont-label good">From a Setup Wizard screen</div>
<table class="ui-table good">
<thead>
<tr>
<th>
Signing in...
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
Your phone is contacting Google.<br>
This can take up to 5 minutes.
</td>
</tr>
</tbody>
</table>
</div>
</div>
<h4 id="simple">Simple</h4>
<ul>
<li>Use short words, active verbs, and common nouns.</li>
<li>Put the most important thing first. “Front-load” the first 11 characters
with the most salient information in the string.</li>
<li>Don’t try to explain subtle differences. They are lost on most users.</li>
</ul>
<p><em>Focus on the user's concern, not technical details</em></p>
<div class="layout-content-row">
<div class="layout-content-col span-6 layout-with-list-item-margins">
<div class="do-dont-label bad">Don't</div>
<table class="ui-table good"><tbody><tr><td>
Manually control GPS to prevent other apps from using it
</td></tr></tbody></table>
</div>
<div class="layout-content-col span-6">
<div class="do-dont-label good">Do</div>
<table class="ui-table good"><tbody><tr><td>
To save power, switch Location mode to Battery saving
</td></tr></tbody></table>
</div>
</div>
<p><em>Put top news first</em></p>
<div class="layout-content-row">
<div class="layout-content-col span-6 layout-with-list-item-margins">
<div class="do-dont-label bad">Don't</div>
<table class="ui-table good"><tbody><tr><td>
77 other people +1’d this, including Larry Page
</td></tr></tbody></table>
</div>
<div class="layout-content-col span-6">
<div class="do-dont-label good">Do</div>
<table class="ui-table good"><tbody><tr><td>
Larry Page and 76 others +1’d this
</td></tr></tbody></table>
</div>
</div>
<p><em>Put the user's goal first</em></p>
<div class="layout-content-row">
<div class="layout-content-col span-6 layout-with-list-item-margins">
<div class="do-dont-label bad">Don't</div>
<table class="ui-table good"><tbody><tr><td>
Touch Next to complete setup using a Wi-Fi connection
</td></tr></tbody></table>
</div>
<div class="layout-content-col span-6">
<div class="do-dont-label good">Do</div>
<table class="ui-table good"><tbody><tr><td>
To finish setup using Wi-Fi, touch Next
</td></tr></tbody></table>
</div>
</div>
<h4 id="friendly">Friendly</h4>
<ul>
<li>Use contractions.</li>
<li>Talk directly to the reader. Use “you” to refer to the reader.</li>
<li>Keep your tone casual and conversational, but avoid slang.</li>
</li>
</ul>
<p><em>Avoid being confusing or annoying</em></p>
<div class="layout-content-row">
<div class="layout-content-col span-6 layout-with-list-item-margins">
<div class="do-dont-label bad">Don't</div>
<table class="ui-table bad">
<thead>
<tr>
<th>
Sorry!
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
Activity MyAppActivity (in application<br />
MyApp) is not responding
</td>
</tr>
</tbody>
</table>
</div>
<div class="layout-content-col span-6">
<div class="do-dont-label good">Do</div>
<table class="ui-table good">
<thead>
<tr>
<th>
MyApp isn’t responding
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
Do you want to close it?
</td>
</tr>
</tbody>
</table>
</div>
</div>
<h4>Words to avoid</h4>
<div style="padding:5px 2.1em;">
<table>
<tr>
<td class="do-dont-label bad" style="width:40%">Don't use</td>
<td class="do-dont-label good" style="width:40%">Use</td>
</tr>
<tr>
<td>one, two, three, four, ...</td>
<td>1, 2, 3, 4, ...</td>
</tr>
<tr>
<td>application</td>
<td>app</td>
</tr>
<tr>
<td>cannot, could not, do not, did not
will not, you will</td>
<td><em>Contractions:</em> can’t, couldn’t, don’t, didn’t won’t, you’ll, and so on</td>
</tr>
<tr>
<td>okay, ok</td>
<td>OK</td>
</tr>
<tr>
<td>please, sorry, thank you</td>
<td><em>Attempts at politeness can annoy the user, especially in messages that say
something has gone wrong.<br />
Exception: In Japanese, “please” is mandatory and imperative verbs should
be localized accordingly (turn on -> please turn on).
</em></td>
</tr>
<tr>
<td>there is, there are, it is<br />
<em>and other “disappeared” subjects (grammatical expletives)</em></td>
<td><em>Use a noun as the subject</em></td>
</tr>
<tr>
<td>abort, kill, terminate</td>
<td>stop, cancel, end, exit</td>
</tr>
<tr>
<td>fail, failed, <em>negative language</em></td>
<td><em>In general, use positive phrasing<br />
(for example, “do” rather than “don’t,” except in cases such as “Don’t show
again,” “Can’t connect,” and so on.)</em></td>
</tr>
<tr>
<td>me, I, my, mine</td>
<td>you, your, yours</td>
</tr>
<tr>
<td>Are you sure? Warning!</td>
<td><em>Tell user the consequence instead, for example, “You’ll lose all photos
and media”</em></td>
</tr>
</table>
</div>
<h2 id="formatting_text">Formatting text</h2>
<h4 id="capitalization">Capitalization</h4>
<ul>
<li>Use sentence-style capitalization for all UI strings: “Words to live by.”</li>
<li>Capitalize all important words in:
<ul>
<li>App names (Calendar, Google Drive)</li>
<li>Named features (Android Beam, Face Unlock)</li>
<li>Proper nouns (Statue of Liberty, San Francisco Giants)</li>
</ul>
</li>
<li>Be conservative. Don't capitalize words that aren't part of a formal feature name:
<ul>
<li>Sim card lock, Home screen, not Sim Card Lock, Home Screen.</li>
</ul>
</li>
</ul>
<h4 id="punctuation">Punctuation</h4>
<ul>
<li><strong>Period.</strong> Don't use a period after a single sentence or
phrase used in isolation, such as in a toast, label, or notification. Wherever two or
more sentences run together, use a period for each sentence. </li>
<li><strong>Ellipsis.</strong> Use the ellipsis character (…) (Option-; on MacOS and &hellip;
in HTML) to indicate
<ul>
<li>Incompleteness, such as an action in progress (“Downloading...”) or truncated text.</li>
<li>That a menu item (such as Print… or Share…) leads to further UI involving significant
choices. Exception: Commands whose wording already implies further (but limited) UI, such
as <strong>Find in page</strong> or <strong>Pick a date</strong>, do not require an
ellipsis. </li>
</ul>
</li>
</ul>