Home | History | Annotate | Download | only in style 
      1 page.title=Writing Style
      2 @jd:body
      3 
      4 <p>When choosing words for your app:</p>
      5 <ol>
      6 <li>
      7 <p><strong>Keep it brief.</strong> Be concise, simple and precise. Start with a 30 character limit (including
      8    spaces), and don't use more unless absolutely necessary.</p>
      9 </li>
     10 <li>
     11 <p><strong>Keep it simple.</strong> Pretend you're speaking to someone who's smart and competent, but doesn't
     12    know technical jargon and may not speak English very well. Use short words, active verbs, and
     13    common nouns.</p>
     14 </li>
     15 <li>
     16 <p><strong>Be friendly.</strong> Use contractions. Talk directly to the reader using second person ("you"). If
     17    your text doesn't read the way you'd say it in casual conversation, it's probably not the way
     18    you should write it. Don't be abrupt or annoying and make the user feel safe, happy and
     19    energized.</p>
     20 </li>
     21 <li>
     22 <p><strong>Put the most important thing first.</strong> The first two words (around 11 characters, including
     23    spaces) should include at least a taste of the most important information in the string. If they
     24    don't, start over.</p>
     25 </li>
     26 <li>
     27 <p><strong>Describe only what's necessary, and no more.</strong> Don't try to explain subtle differences. They
     28    will be lost on most users.</p>
     29 </li>
     30 <li>
     31 <p><strong>Avoid repetition.</strong> If a significant term gets repeated within a screen or block of text, find
     32    a way to use it just once.</p>
     33 </li>
     34 </ol>
     35 
     36 <h2 id="examples">Examples</h2>
     37 
     38 <ol><li class="value-1"><strong>Keep it brief.</strong> From the setup wizard:</ol>
     39 
     40 <div class="layout-content-row">
     41   <div class="layout-content-col span-6 layout-with-list-item-margins">
     42 
     43     <div class="do-dont-label bad">Too formal</div>
     44 
     45     <table class="ui-table good"><tbody><tr><td>
     46     Consult the documentation that came with your phone for further instructions.
     47     </td></tr></tbody></table>
     48 
     49   </div>
     50   <div class="layout-content-col span-6">
     51 
     52     <div class="do-dont-label good">Better</div>
     53 
     54     <table class="ui-table good"><tbody><tr><td>
     55     Read the instructions that came with your phone.
     56     </td></tr></tbody></table>
     57 
     58   </div>
     59 </div>
     60 
     61 <div class="vspace size-1">&nbsp;</div>
     62 
     63 <ol><li class="value-2"><strong>Keep it simple.</strong> From the Location settings screen:</ol>
     64 
     65 <div class="layout-content-row">
     66   <div class="layout-content-col span-6 layout-with-list-item-margins">
     67 
     68     <div class="do-dont-label bad">Confusing</div>
     69 
     70     <table class="ui-table bad">
     71     <thead>
     72       <tr>
     73         <th>
     74         Use GPS satellites
     75         </th>
     76       </tr>
     77     </thead>
     78     <tbody>
     79       <tr>
     80         <td>
     81         When locating, accurate to street level.
     82         </td>
     83       </tr>
     84     </tbody>
     85     </table>
     86 
     87   </div>
     88   <div class="layout-content-col span-6">
     89 
     90     <div class="do-dont-label good">Better</div>
     91 
     92     <table class="ui-table good">
     93     <thead>
     94       <tr>
     95         <th>
     96         GPS
     97         </th>
     98       </tr>
     99     </thead>
    100     <tbody>
    101       <tr>
    102         <td>
    103         Let apps use satellites to pinpoint your location.
    104         </td>
    105       </tr>
    106     </tbody>
    107     </table>
    108 
    109   </div>
    110 </div>
    111 
    112 <div class="vspace size-1">&nbsp;</div>
    113 
    114 <ol><li class="value-3"><strong>Be friendly.</strong> Dialog that appears when an application
    115 crashes:</ol>
    116 
    117 <div class="layout-content-row">
    118   <div class="layout-content-col span-6 layout-with-list-item-margins">
    119 
    120     <div class="do-dont-label bad">Confusing and annoying&mdash;"Sorry" just rubs salt in the
    121     wound.</div>
    122 
    123     <table class="ui-table bad">
    124     <thead>
    125       <tr>
    126         <th colspan="3">
    127         Sorry!
    128         </th>
    129       </tr>
    130     </thead>
    131     <tbody>
    132       <tr>
    133         <td colspan="3">
    134         Activity MyAppActivity (in application MyApp)
    135         is not responding.
    136         </td>
    137       </tr>
    138     </tbody>
    139     <tfoot>
    140       <tr>
    141         <td width="33%">Force close</td>
    142         <td width="33%">Wait</td>
    143         <td width="33%">Report</td>
    144       </tr>
    145     </tbody>
    146     </table>
    147 
    148   </div>
    149   <div class="layout-content-col span-6">
    150 
    151     <div class="do-dont-label good">Shorter, more direct, no faux-apologetic title:<br><br></div>
    152 
    153     <table class="ui-table good">
    154     <thead>
    155       <tr>
    156         <th colspan="3">
    157         MyApp isn't responding.
    158         </th>
    159       </tr>
    160     </thead>
    161     <tbody>
    162       <tr>
    163         <td colspan="3">
    164         Do you want to close it?
    165         </td>
    166       </tr>
    167     </tbody>
    168     <tfoot>
    169       <tr>
    170         <td width="33%">Wait</td>
    171         <td width="33%">Report</td>
    172         <td width="33%">Close</td>
    173       </tr>
    174     </tbody>
    175     </table>
    176 
    177   </div>
    178 </div>
    179 
    180 <div class="vspace size-1">&nbsp;</div>
    181 
    182 <ol><li class="value-4"><strong>Put the most important thing first.</strong></ol>
    183 
    184 <div class="layout-content-row">
    185   <div class="layout-content-col span-6 layout-with-list-item-margins">
    186 
    187     <div class="do-dont-label bad">Top news last</div>
    188 
    189     <table class="ui-table bad"><tbody><tr><td>
    190     77 other people +1'd this, including Larry Page.
    191     </td></tr></tbody></table>
    192 
    193   </div>
    194   <div class="layout-content-col span-6">
    195 
    196     <div class="do-dont-label good">Top news first</div>
    197 
    198     <table class="ui-table good"><tbody><tr><td>
    199     Larry Page and 77 others +1'd this.
    200     </td></tr></tbody></table>
    201 
    202   </div>
    203 </div>
    204 
    205 <div class="layout-content-row">
    206   <div class="layout-content-col span-6 layout-with-list-item-margins">
    207 
    208     <div class="do-dont-label bad">Task last</div>
    209 
    210     <table class="ui-table bad"><tbody><tr><td>
    211     Touch Next to complete setup using a Wi-Fi connection.
    212     </td></tr></tbody></table>
    213 
    214   </div>
    215   <div class="layout-content-col span-6">
    216 
    217     <div class="do-dont-label good">Task first</div>
    218 
    219     <table class="ui-table good"><tbody><tr><td>
    220     To finish setup using Wi-Fi, touch Next.
    221     </td></tr></tbody></table>
    222 
    223   </div>
    224 </div>
    225 
    226 <div class="vspace size-1">&nbsp;</div>
    227 
    228 <ol><li class="value-5"><strong>Describe only what's necessary, and no more.</strong></ol>
    229 
    230 <div class="layout-content-row">
    231   <div class="layout-content-col span-6 layout-with-list-item-margins">
    232 
    233     <div class="do-dont-label bad">From a Setup Wizard screen</div>
    234 
    235     <table class="ui-table bad">
    236     <thead>
    237       <tr>
    238         <th>
    239         Signing in...
    240         </th>
    241       </tr>
    242     </thead>
    243     <tbody>
    244       <tr>
    245         <td>
    246         Your phone needs to communicate with<br>
    247         Google servers to sign in to your account.<br>
    248         This may take up to five minutes.
    249         </td>
    250       </tr>
    251     </tbody>
    252     </table>
    253 
    254   </div>
    255   <div class="layout-content-col span-6">
    256 
    257     <div class="do-dont-label good">From a Setup Wizard screen</div>
    258 
    259     <table class="ui-table good">
    260     <thead>
    261       <tr>
    262         <th>
    263         Signing in...
    264         </th>
    265       </tr>
    266     </thead>
    267     <tbody>
    268       <tr>
    269         <td>
    270         Your phone is contacting Google.<br>
    271         This can take up to 5 minutes.
    272         </td>
    273       </tr>
    274     </tbody>
    275     </table>
    276 
    277   </div>
    278 </div>
    279