diff options
Diffstat (limited to 'docs/html/design/style/writing.jd')
| -rw-r--r-- | docs/html/design/style/writing.jd | 322 |
1 files changed, 0 insertions, 322 deletions
diff --git a/docs/html/design/style/writing.jd b/docs/html/design/style/writing.jd deleted file mode 100644 index 0c62a55..0000000 --- a/docs/html/design/style/writing.jd +++ /dev/null @@ -1,322 +0,0 @@ -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="cols"> - <div class="col-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="col-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="cols"> - <div class="col-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="col-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="cols"> - <div class="col-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="col-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="cols"> - <div class="col-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="col-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="cols"> - <div class="col-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="col-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="cols"> - <div class="col-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="col-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> |