Roman Nurik | b99ae73 | 2012-03-06 12:26:15 -0800 | [diff] [blame] | 1 | page.title=Writing Style |
Scott Main | 64d5103 | 2013-04-12 14:00:30 -0700 | [diff] [blame] | 2 | page.tags="dialog","toast","notification" |
Roman Nurik | b99ae73 | 2012-03-06 12:26:15 -0800 | [diff] [blame] | 3 | @jd:body |
| 4 | |
Dirk Dougherty | 0b73403 | 2013-10-19 11:43:41 -0700 | [diff] [blame] | 5 | <h2 id="voa">Android's Voice</h2> |
Roman Nurik | b99ae73 | 2012-03-06 12:26:15 -0800 | [diff] [blame] | 6 | |
Dirk Dougherty | 0b73403 | 2013-10-19 11:43:41 -0700 | [diff] [blame] | 7 | <p>When writing text that appears in your app, keep it concise, simple, and friendly.</p> |
Roman Nurik | b99ae73 | 2012-03-06 12:26:15 -0800 | [diff] [blame] | 8 | |
Dirk Dougherty | 0b73403 | 2013-10-19 11:43:41 -0700 | [diff] [blame] | 9 | <h4 id="concise">Concise</h4> |
| 10 | |
| 11 | <ul> |
| 12 | <li>Describe only what the user needs to know.</li> |
| 13 | <li>Eliminate redundancy, such as titles that restate the body of an information box.</li> |
| 14 | <li>Keep text as short as possible.</li> |
| 15 | </ul> |
| 16 | |
| 17 | <p><em>Avoid wordy, stilted text</em></p> |
Roman Nurik | b99ae73 | 2012-03-06 12:26:15 -0800 | [diff] [blame] | 18 | |
| 19 | <div class="layout-content-row"> |
Roman Nurik | b20f120 | 2012-03-29 13:28:13 -0700 | [diff] [blame] | 20 | <div class="layout-content-col span-6 layout-with-list-item-margins"> |
Roman Nurik | b99ae73 | 2012-03-06 12:26:15 -0800 | [diff] [blame] | 21 | |
Dirk Dougherty | 0b73403 | 2013-10-19 11:43:41 -0700 | [diff] [blame] | 22 | <div class="do-dont-label bad">Don't</div> |
Roman Nurik | b99ae73 | 2012-03-06 12:26:15 -0800 | [diff] [blame] | 23 | |
Roman Nurik | b20f120 | 2012-03-29 13:28:13 -0700 | [diff] [blame] | 24 | <table class="ui-table good"><tbody><tr><td> |
Roman Nurik | b99ae73 | 2012-03-06 12:26:15 -0800 | [diff] [blame] | 25 | Consult the documentation that came with your phone for further instructions. |
| 26 | </td></tr></tbody></table> |
| 27 | |
| 28 | </div> |
| 29 | <div class="layout-content-col span-6"> |
| 30 | |
Dirk Dougherty | 0b73403 | 2013-10-19 11:43:41 -0700 | [diff] [blame] | 31 | <div class="do-dont-label good">Do</div> |
Roman Nurik | b99ae73 | 2012-03-06 12:26:15 -0800 | [diff] [blame] | 32 | |
Roman Nurik | b20f120 | 2012-03-29 13:28:13 -0700 | [diff] [blame] | 33 | <table class="ui-table good"><tbody><tr><td> |
Roman Nurik | b99ae73 | 2012-03-06 12:26:15 -0800 | [diff] [blame] | 34 | Read the instructions that came with your phone. |
| 35 | </td></tr></tbody></table> |
| 36 | |
| 37 | </div> |
| 38 | </div> |
| 39 | |
Dirk Dougherty | 0b73403 | 2013-10-19 11:43:41 -0700 | [diff] [blame] | 40 | <p><em>Don't provide unnecessary information</em></p> |
Roman Nurik | b99ae73 | 2012-03-06 12:26:15 -0800 | [diff] [blame] | 41 | |
| 42 | <div class="layout-content-row"> |
Roman Nurik | b20f120 | 2012-03-29 13:28:13 -0700 | [diff] [blame] | 43 | <div class="layout-content-col span-6 layout-with-list-item-margins"> |
Roman Nurik | b99ae73 | 2012-03-06 12:26:15 -0800 | [diff] [blame] | 44 | |
Roman Nurik | b20f120 | 2012-03-29 13:28:13 -0700 | [diff] [blame] | 45 | <div class="do-dont-label bad">From a Setup Wizard screen</div> |
Roman Nurik | b99ae73 | 2012-03-06 12:26:15 -0800 | [diff] [blame] | 46 | |
Roman Nurik | b20f120 | 2012-03-29 13:28:13 -0700 | [diff] [blame] | 47 | <table class="ui-table bad"> |
Roman Nurik | b99ae73 | 2012-03-06 12:26:15 -0800 | [diff] [blame] | 48 | <thead> |
| 49 | <tr> |
| 50 | <th> |
| 51 | Signing in... |
| 52 | </th> |
| 53 | </tr> |
| 54 | </thead> |
| 55 | <tbody> |
| 56 | <tr> |
| 57 | <td> |
| 58 | Your phone needs to communicate with<br> |
| 59 | Google servers to sign in to your account.<br> |
| 60 | This may take up to five minutes. |
| 61 | </td> |
| 62 | </tr> |
| 63 | </tbody> |
| 64 | </table> |
| 65 | |
| 66 | </div> |
| 67 | <div class="layout-content-col span-6"> |
| 68 | |
Roman Nurik | b20f120 | 2012-03-29 13:28:13 -0700 | [diff] [blame] | 69 | <div class="do-dont-label good">From a Setup Wizard screen</div> |
Roman Nurik | b99ae73 | 2012-03-06 12:26:15 -0800 | [diff] [blame] | 70 | |
Roman Nurik | b20f120 | 2012-03-29 13:28:13 -0700 | [diff] [blame] | 71 | <table class="ui-table good"> |
Roman Nurik | b99ae73 | 2012-03-06 12:26:15 -0800 | [diff] [blame] | 72 | <thead> |
| 73 | <tr> |
| 74 | <th> |
| 75 | Signing in... |
| 76 | </th> |
| 77 | </tr> |
| 78 | </thead> |
| 79 | <tbody> |
| 80 | <tr> |
| 81 | <td> |
| 82 | Your phone is contacting Google.<br> |
| 83 | This can take up to 5 minutes. |
| 84 | </td> |
| 85 | </tr> |
| 86 | </tbody> |
| 87 | </table> |
| 88 | |
| 89 | </div> |
| 90 | </div> |
Dirk Dougherty | 0b73403 | 2013-10-19 11:43:41 -0700 | [diff] [blame] | 91 | |
| 92 | <h4 id="simple">Simple</h4> |
| 93 | |
| 94 | <ul> |
| 95 | <li>Use short words, active verbs, and common nouns.</li> |
| 96 | <li>Put the most important thing first. “Front-load” the first 11 characters |
| 97 | with the most salient information in the string.</li> |
| 98 | <li>Don’t try to explain subtle differences. They are lost on most users.</li> |
| 99 | </ul> |
| 100 | |
| 101 | <p><em>Focus on the user's concern, not technical details</em></p> |
| 102 | |
| 103 | <div class="layout-content-row"> |
| 104 | <div class="layout-content-col span-6 layout-with-list-item-margins"> |
| 105 | |
| 106 | <div class="do-dont-label bad">Don't</div> |
| 107 | |
| 108 | <table class="ui-table good"><tbody><tr><td> |
| 109 | Manually control GPS to prevent other apps from using it |
| 110 | </td></tr></tbody></table> |
| 111 | |
| 112 | </div> |
| 113 | <div class="layout-content-col span-6"> |
| 114 | |
| 115 | <div class="do-dont-label good">Do</div> |
| 116 | |
| 117 | <table class="ui-table good"><tbody><tr><td> |
| 118 | To save power, switch Location mode to Battery saving |
| 119 | </td></tr></tbody></table> |
| 120 | |
| 121 | </div> |
| 122 | </div> |
| 123 | |
| 124 | <p><em>Put top news first</em></p> |
| 125 | |
| 126 | <div class="layout-content-row"> |
| 127 | <div class="layout-content-col span-6 layout-with-list-item-margins"> |
| 128 | |
| 129 | <div class="do-dont-label bad">Don't</div> |
| 130 | |
| 131 | <table class="ui-table good"><tbody><tr><td> |
| 132 | 77 other people +1’d this, including Larry Page |
| 133 | </td></tr></tbody></table> |
| 134 | |
| 135 | </div> |
| 136 | <div class="layout-content-col span-6"> |
| 137 | |
| 138 | <div class="do-dont-label good">Do</div> |
| 139 | |
| 140 | <table class="ui-table good"><tbody><tr><td> |
| 141 | Larry Page and 76 others +1’d this |
| 142 | </td></tr></tbody></table> |
| 143 | |
| 144 | </div> |
| 145 | </div> |
| 146 | |
| 147 | <p><em>Put the user's goal first</em></p> |
| 148 | |
| 149 | <div class="layout-content-row"> |
| 150 | <div class="layout-content-col span-6 layout-with-list-item-margins"> |
| 151 | |
| 152 | <div class="do-dont-label bad">Don't</div> |
| 153 | |
| 154 | <table class="ui-table good"><tbody><tr><td> |
| 155 | Touch Next to complete setup using a Wi-Fi connection |
| 156 | </td></tr></tbody></table> |
| 157 | |
| 158 | </div> |
| 159 | <div class="layout-content-col span-6"> |
| 160 | |
| 161 | <div class="do-dont-label good">Do</div> |
| 162 | |
| 163 | <table class="ui-table good"><tbody><tr><td> |
| 164 | To finish setup using Wi-Fi, touch Next |
| 165 | </td></tr></tbody></table> |
| 166 | |
| 167 | </div> |
| 168 | </div> |
| 169 | |
| 170 | |
| 171 | <h4 id="friendly">Friendly</h4> |
| 172 | |
| 173 | <ul> |
| 174 | <li>Use contractions.</li> |
| 175 | <li>Talk directly to the reader. Use “you” to refer to the reader.</li> |
| 176 | <li>Keep your tone casual and conversational, but avoid slang.</li> |
| 177 | </li> |
| 178 | </ul> |
| 179 | |
| 180 | <p><em>Avoid being confusing or annoying</em></p> |
| 181 | <div class="layout-content-row"> |
| 182 | <div class="layout-content-col span-6 layout-with-list-item-margins"> |
| 183 | <div class="do-dont-label bad">Don't</div> |
| 184 | <table class="ui-table bad"> |
| 185 | <thead> |
| 186 | <tr> |
| 187 | <th> |
| 188 | Sorry! |
| 189 | </th> |
| 190 | </tr> |
| 191 | </thead> |
| 192 | <tbody> |
| 193 | <tr> |
| 194 | <td> |
| 195 | Activity MyAppActivity (in application<br /> |
| 196 | MyApp) is not responding |
| 197 | </td> |
| 198 | </tr> |
| 199 | </tbody> |
| 200 | </table> |
| 201 | |
| 202 | </div> |
| 203 | <div class="layout-content-col span-6"> |
| 204 | <div class="do-dont-label good">Do</div> |
| 205 | <table class="ui-table good"> |
| 206 | <thead> |
| 207 | <tr> |
| 208 | <th> |
| 209 | MyApp isn’t responding |
| 210 | </th> |
| 211 | </tr> |
| 212 | </thead> |
| 213 | <tbody> |
| 214 | <tr> |
| 215 | <td> |
| 216 | Do you want to close it? |
| 217 | </td> |
| 218 | </tr> |
| 219 | </tbody> |
| 220 | </table> |
| 221 | </div> |
| 222 | </div> |
| 223 | |
| 224 | |
| 225 | <h4>Words to avoid</h4> |
| 226 | |
| 227 | <div style="padding:5px 2.1em;"> |
| 228 | <table> |
| 229 | <tr> |
| 230 | <td class="do-dont-label bad" style="width:40%">Don't use</td> |
| 231 | <td class="do-dont-label good" style="width:40%">Use</td> |
| 232 | </tr> |
| 233 | <tr> |
| 234 | <td>one, two, three, four, ...</td> |
| 235 | <td>1, 2, 3, 4, ...</td> |
| 236 | </tr> |
| 237 | <tr> |
| 238 | <td>application</td> |
| 239 | <td>app</td> |
| 240 | </tr> |
| 241 | <tr> |
| 242 | <td>cannot, could not, do not, did not |
| 243 | will not, you will</td> |
| 244 | <td><em>Contractions:</em> can’t, couldn’t, don’t, didn’t won’t, you’ll, and so on</td> |
| 245 | </tr> |
| 246 | <tr> |
| 247 | <td>okay, ok</td> |
| 248 | <td>OK</td> |
| 249 | </tr> |
| 250 | <tr> |
| 251 | <td>please, sorry, thank you</td> |
| 252 | <td><em>Attempts at politeness can annoy the user, especially in messages that say |
| 253 | something has gone wrong.<br /> |
| 254 | Exception: In Japanese, “please” is mandatory and imperative verbs should |
| 255 | be localized accordingly (turn on -> please turn on). |
| 256 | </em></td> |
| 257 | </tr> |
| 258 | <tr> |
| 259 | <td>there is, there are, it is<br /> |
| 260 | <em>and other “disappeared” subjects (grammatical expletives)</em></td> |
| 261 | <td><em>Use a noun as the subject</em></td> |
| 262 | </tr> |
| 263 | <tr> |
| 264 | <td>abort, kill, terminate</td> |
| 265 | <td>stop, cancel, end, exit</td> |
| 266 | </tr> |
| 267 | <tr> |
| 268 | <td>fail, failed, <em>negative language</em></td> |
| 269 | <td><em>In general, use positive phrasing<br /> |
| 270 | (for example, “do” rather than “don’t,” except in cases such as “Don’t show |
| 271 | again,” “Can’t connect,” and so on.)</em></td> |
| 272 | </tr> |
| 273 | <tr> |
| 274 | <td>me, I, my, mine</td> |
| 275 | <td>you, your, yours</td> |
| 276 | </tr> |
| 277 | <tr> |
| 278 | <td>Are you sure? Warning!</td> |
| 279 | <td><em>Tell user the consequence instead, for example, “You’ll lose all photos |
| 280 | and media”</em></td> |
| 281 | </tr> |
| 282 | </table> |
| 283 | |
| 284 | </div> |
| 285 | |
| 286 | <h2 id="formatting_text">Formatting text</h2> |
| 287 | |
| 288 | <h4 id="capitalization">Capitalization</h4> |
| 289 | |
| 290 | <ul> |
| 291 | <li>Use sentence-style capitalization for all UI strings: “Words to live by.”</li> |
| 292 | <li>Capitalize all important words in: |
| 293 | <ul> |
| 294 | <li>App names (Calendar, Google Drive)</li> |
| 295 | <li>Named features (Android Beam, Face Unlock)</li> |
| 296 | <li>Proper nouns (Statue of Liberty, San Francisco Giants)</li> |
| 297 | </ul> |
| 298 | </li> |
| 299 | <li>Be conservative. Don't capitalize words that aren't part of a formal feature name: |
| 300 | <ul> |
| 301 | <li>Sim card lock, Home screen, not Sim Card Lock, Home Screen.</li> |
| 302 | </ul> |
| 303 | </li> |
| 304 | </ul> |
| 305 | |
| 306 | |
| 307 | <h4 id="punctuation">Punctuation</h4> |
| 308 | <ul> |
| 309 | <li><strong>Period.</strong> Don't use a period after a single sentence or |
| 310 | phrase used in isolation, such as in a toast, label, or notification. Wherever two or |
| 311 | more sentences run together, use a period for each sentence. </li> |
| 312 | <li><strong>Ellipsis.</strong> Use the ellipsis character (…) (Option-; on MacOS and &hellip; |
| 313 | in HTML) to indicate |
| 314 | <ul> |
| 315 | <li>Incompleteness, such as an action in progress (“Downloading...”) or truncated text.</li> |
| 316 | <li>That a menu item (such as Print… or Share…) leads to further UI involving significant |
| 317 | choices. Exception: Commands whose wording already implies further (but limited) UI, such |
| 318 | as <strong>Find in page</strong> or <strong>Pick a date</strong>, do not require an |
| 319 | ellipsis. </li> |
| 320 | </ul> |
| 321 | </li> |
| 322 | </ul> |