-
Notifications
You must be signed in to change notification settings - Fork 0
/
interface-writing.html
439 lines (345 loc) · 25.5 KB
/
interface-writing.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
<!DOCTYPE html>
<html>
<head>
<title>Interface Writing: Code for Humans</title>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link href="reset.css" rel="stylesheet">
<link href="common.css" rel="stylesheet">
<!-- The three different styling directions: -->
<!-- <link href="direction-1.css" rel="stylesheet">
<link href="direction-2.css" rel="stylesheet">
<link href="direction-3.css" rel="stylesheet"> -->
</head>
<body>
<div>
<div class="landing-page_container">
<header>
<!-- <p class="special-background-character">%</p> -->
<h1>Interface Writing: Code for Humans</h1>
<p><span class="header_author">Nicole Fenton</span></p>
<p class="header_subtext header_subtext-top-2 is-blue">
<em>I gave this talk at Burlington Ruby Conference in Vermont and Blend Conference in Charlotte, North Carolina.</em>
</p>
</header>
<nav>
<ul>
<li><a href="index.html"><span>@</span> <span>Home</span></a></li>
<li><a href="words-as-materials.html"><span>&</span> <span>Materials</span></a></li>
<li class="navbar_red-pen-mark"><a href="interface-writing.html"><span>%</span> <span>Interface</span></a></li>
<li><a href="what-has-writing.html"><span>?</span> <span>For Design</span></a></li>
</ul>
</nav>
</div>
<nav class="navbar-fixed">
<ul>
<li><a href="index.html">@</a></li>
<li><a href="words-as-materials.html">&</a></li>
<li class="navbar-bottom_red-pen-mark"><a href="interface-writing.html">%</a></li>
<li><a href="what-has-writing.html">?</a></li>
</ul>
</nav>
</div>
<main>
<article>
<section>
<p>The web and the world are full of instructions. Everywhere you go, signs and people are telling you what to do.</p>
<p>Walk. Don't walk.</p>
<p>Follow me please. Stop. Hang on. Please stand clear.</p>
<p>Fasten your seatbelt. Read this.</p>
<p>Do this.</p>
<p>Take this. Buy this. Find us on Facebook. Please enter your name.</p>
<p>You get the idea. So bossy.</p>
<p>Think about the app you're building right now.</p>
<p>What actions can people take? What are you asking them to do? What are you allowing them to do? What are the rules and dead-ends? What sort of language do you use to guide people?</p>
<p>Whatever you're building, you need to think about the content in the database and the instructions around it. I call those things <em>interface writing</em>. Some people call them <em>microcopy</em> since they're usually short.</p>
</section>
</article>
<article class="container_style-two border-top">
<header>
<h2>Interface writing</h2>
</header>
<section>
<ul class="ul-li_normal">
<li>buttons</li>
<li>notifications</li>
<li>errors and alerts</li>
<li>forms</li>
<li>in-app disclosures</li>
<li>links</li>
<li>navigation</li>
<li>product tours</li>
<li>setting names</li>
<li>tooltips</li>
<li>transactional emails</li>
</ul>
<p>
From navigation links and buttons to product tours, forms, and error messages–every string in your database is an instruction. These are your signposts, and they grab your reader's attention.
</p>
<p>
As developers and writers, you have a lot of power. The user wants something. Maybe it's information, an easier way of doing things, chocolate chip cookies, or hilarious cat videos.
</p>
<p>
With clear instructions and a warm tone, you can help them find what they need quickly without having to ask anyone for help.
</p>
<p>
Let me tell you a story. This is my dad. He's a test engineer. He works on semiconductors and develops tests for parts and batteries. So growing up, we always had computers around the house and the latest in PC technology.
</p>
<p>
We used to have this program called Dr. Sbaitso, which you may have heard of. It was a computerized psychologist slash artifical intelligence program designed to show off sound cards, but I thought it was a game and used to play with it for hours.
</p>
<p>
This is what it looked like. A typical, boring DOS interface.
</p>
<p>
Dr. Sbaitso would tell me what to do and I’d tell him about my 9-year-old problems. At the time, I was usually hungry or tired or bored. So I would answer in one of three ways.
</p>
<p>
And then he would ask, “Why are you bored?” or “Are you sure you are bored?” And then I would say, yes, I’m sure and start repeating myself. Next thing I know, he’s shouting a zen koan at me like this:
</p>
<p>
(image: interfaces15.png alt: zen koan">
</p>
<p>
And this would result in me having a tiny existential freakout. I would get sick of that topic and switch over to cussing or saying something inappropriate. And if I did that long enough, Dr. Sbaitso would throw a <a href="https://www.youtube.com/watch?v=1GaWfCWcW3M">parity error</a>.
</p>
<p>
The reason I bring this up is that it shapes how I think about interface writing. Dr. Sbaitso was pre-programmed with all of these different strings to respond with.
</p>
<!-- text imagery "DO YOU BELIEVE IT IS NORMAL TO {BE BORED}? WHAT Strings RED} {NICOLE}, DON'T BE SO DEFENSIVE -->
<div>
<p class="text-imagery_interface-writing">
DO YOU BELIEVE IT IS NORMAL TO <span class="black-color">{BE BORED}?</span> WHAT <span class="red-color">Strings RED}</span> <span class="blue-color">{NICOLE}</span>, DON'T BE <span class="black-color">SO DEFENSIVE</span>
</p>
</div>
<p>
And while most of them were cold, poorly punctuated, and hilariously impersonal, the model of prompting the reader—this kind of call and response—really worked. It felt like a conversation. Maybe it was a little awkward, but it was a good start.
</p>
<p>
When you’re writing for the web, you’re having the same sort of conversation with your readers. You’re telling them to do something or asking them a question. Above all, you want it to make sense and feel natural to them. Our strings have to be useful—not funny—so we need to do the extra work of figuring out what our readers need. That makes it easier to show people around, ask for more of their time, or get them to take a particular action.
</p>
<p>
In his essay <a href="https://medium.com/weird-future/we-have-always-coded-2acc5ba75929">We Have Always Coded</a>, Tim Maly says:
</p>
<blockquote>
<mark class="highlighter-color-2">“It is no coincidence that many women have compared weaving code to instructing a child. With both kids and computers, you must carefully think through what you want them to do, and then carefully phrase your commands.”</mark>
</blockquote>
<p>From a high level, these are my goals when I'm writing strings:</p>
<ul class="circle-container">
<li>Be clear.</li>
<li>Be kind.</li>
<li>Be careful.</li>
<li>Be honest.</li>
</ul>
<p>
Focus on the reader’s needs. Think about the implications of what you’re asking for. Be honest about what you’re doing with the data. That’s extremely important.
</p>
<!-- text imagery CITY STATE COMPANY CREDIT CARD DELIVERY DATE RATING PHOTO IP ADDRESS EMAIL GENDER MARTIAL STATUS AGE BIRTHDAY SOCIAL SECURITY NUMBER LANGUAGE INCOME TITLE -->
<div>
<p class="text-imagery_interface-writing">
<span class="black-color">CITY</span> <span class="red-color">STATE</span> <span class="blue-color">COMPANY</span> <span class="accent-color">CREDIT CARD</span> <span class="black-color">DELIVERY DATE</span> <span class="red-color">RATING</span> <span class="blue-color">PHOTO</span> <span class="accent-color">IP ADDRESS</span> <span class="black-color">EMAIL</span> <span class="red-color">GENDER</span> <span class="blue-color">MARTIAL STATUS</span> <span class="accent-color">AGE</span> <span class="black-color">BIRTHDAY</span> <span class="red-color">SOCIAL SECURITY NUMBER</span> <span class="blue-color">LANGUAGE</span> <span class="accent-color">INCOME</span> <span class="black-color">TITLE</span>
</p>
</div>
<p>
Frank Chimero says, “Every form is a question.” What are you asking through forms and flows? How can you make those questions meaningful and generous for your users?
</p>
<p>
Here are some examples of things you might be asking:
</p>
<ul class="ul-li_normal">
<li>How can we hep you?</li>
<li>What are you interested in?</li>
<li>What do you think of this product?</li>
<li>Do you need this in a hurry?</li>
<li>Where do you live?</li>
<li>Are you married or not?</li>
<li>Where are you right now?</li>
<li>How did you hear about us?</li>
<li>Are you planning to go to this event?</li>
<li>Are you willing to pay for this?</li>
<li>Is it okay if we share this information?</li>
<li>What do you think about when you're alone?</li>
</ul>
<p>
You probably wouldn’t ask a complete stranger these things without a conversation or consent.
</p>
<p>
Each of these interactions should feel like a conversation between two people who trust each other and deserve each other’s trust. It can’t be one-sided. Unless you want to be cold like Dr. Sbaitso or creepy like HAL, you need to take the time to think about these prompts and put yourself in the reader’s shoes. So let’s talk about how to do this.
</p>
</section>
</article>
<article class="container_style-three">
<header>
<div class="container_style-three-navbar">
<h2>Tips</h2>
<div>
<ul>
<li><a href="#start-with">1. Start with questions</a></li>
<li><a href="#be-a-good-tour-guide">2. Be a good tour guide</a></li>
<li><a href="#turn-your-chair">3. Turn your chair</a></li>
<li><a href="#show-you-care">4. Show you Care</a></li>
<li><a href="#write-iteratively">5. Write iteratively</a></li>
</ul>
</div>
</div>
</header>
<section>
<!-- <ul class="ul-li_normal">
<li>Start with questions.</li>
<li>Be a good tour guide.</li>
<li>Turn your chair.</li>
<li>Show you care.</li>
<li>Write iteratively.</li>
</ul> -->
<section id="start-with">
<h3>1. Start with questions.</h3>
<p>
It’s easy to ship something out in a hurry. Before you do, ask yourself a few simple questions:
</p>
<ul class="ul-li_normal">
<li>What is the user trying to do?</li>
<li>What might they be feeling?</li>
<li>How did they get here?</li>
<li>What happens next?</li>
<li>What do they need to understand?</li>
<li>Why does this matter to them?</li>
</ul>
</section>
<section id="be-a-good-tour-guide">
<h3>2. Be a good tour guide.</h3>
<p>
Think about what you’d do if one of your close friends came to visit you at work, or maybe they’re in from out of town. You’d probably show them a few of your favorite things. Give the reader that same sort of care. You know your apps and websites better than most people, so use that to your advantage.
</p>
<p>
If you’re not sure where to start, make a map for yourself. Take screenshots of each part of a flow and look at them together. Start with your signup, checkout, or donation flows. See where you can add specific details and useful examples to simplify your instructions.
</p>
<p>
Think about the hidden gems on your site too. If the user isn’t ready to make a purchase or sign up, what else can they do? I like to think of this as the <em>Choose Your Own Adventure</em> approach to web design. Don’t leave the user hanging, and watch out for dead-ends. Tell them what to expect and help them accomplish their goal.
</p>
<p>
Remember that you’re working with hypertext. You can include links or images to make your point.
</p>
<p>
Here’s an example from <a href="https://www.pinterest.com/">Pinterest</a>. You can see the cocktail my friend Tom pinned, along with other pins he relates to this one and other pins from the source. Pinterest is also prompting me to sign up, since it only takes a second or two. They’re making all of those paths clear.
</p>
<p>
Every now and then, check your terms for clarity too. Make a list of the buttons and navigation links on your site to make sure they’re consistent. Some people call this a <em>nomenclature audit</em>. Here are some examples from <a href="https://basecamp.com/">Basecamp</a>:
</p>
<ul class="circle-container_content-style-three">
<li>Log in</li>
<li>Sign up today</li>
<li>Sign in</li>
<li>Edit my identity</li>
<li>Edit your info</li>
<li>Settings</li>
<li>Sign out</li>
</ul>
<p>
Right away, you can see which ones are too similar. They’re using both “Log in” and “Sign in,” so I’d suggest cutting the “Log in” language to simplify. You can also see that they’re having a trouble deciding if the reader is “you” or “me.” I usually go with “you” to avoid the confusion, but you could also cut the pronouns and possessive adjectives.
</p>
<p>
The terms you choose are a style choice; it’s not about right and wrong. But you should be consistent and match the language your users relate to. If you call something “notifications” in one place, call them “notifications” everywhere. That will help you reduce cognitive load on your readers and save money on translations, too.
</p>
</section>
<section id="turn-your-chair">
<h3>3. Turn your chair</h3>
<p>
Shift your focus to your readers. Talk <em>to</em> them, not <em>at</em> them. Use positive language and avoid yammering on about your company or your interface. The system isn’t the point.
</p>
<p>
Here’s a great example from Square Cash.
</p>
<p>
They’re telling me exactly what happened—I sent $50 to my husband—without yammering on about themselves. They didn’t say, “We have received your request to send $50...” or “Thanks for using Square Cash, the best way to send cash monies...” And that little “Report problem” link is simple and clear.
</p>
<p>
Here’s another example from Oyster, a book subscription service:
</p>
<p>
I signed up for their trial and they sent me a link to their mobile app. But instead of talking about themselves or explaining the features, they’re helping me get right to it. They say, “Why are you still reading this email? Download the app and dive into your first book!” I love that.
</p>
</section>
<section id="show-you-care">
<h3>4. Show you care</h3>
<p>
Now’s the time when I’ll tell you what <em>not</em> to do, since some people find that useful.
</p>
<p>
<strong>Don't assume you're the core audience.</strong> Most of the time, we’re not designing for ourselves. Think about the universe of people out there. Word choice is extremely important when you’re trying to grow.
</p>
<p>
<strong>Avoid jargon and catchphrases.</strong> Cut the bullshit. You don’t have to be hip or clever, but you do have to be nice.
</p>
<p>
<strong>Don’t assume dichotomies or binaries will do the trick.</strong> Not everything will fit into a boolean. Real life is complicated. As an example, some people are neither male nor female. They’re still people and they deserve our consideration.
</p>
<p>
<strong>Don’t interrupt.</strong> Keep things focused and make sure this is the best time to deliver this message.
</p>
<p>
<strong>Don’t be a robot.</strong> Don’t do this:
</p>
<p>
One way to avoid this is to read your work aloud before you ship it. If you work in an open office, it may seem embarrassing to mumble strings to yourself, but it makes a huge difference. Make sure it sounds like you, not too formal or stuffy.
</p>
<p>
Here’s a good example from GitHub.
</p>
<p>
It sounds like it came from a person—and they get bonus points for recommending support links while the page is out of commission.
</p>
<p>
Here’s one from MailChimp.
</p>
<p>
It’s friendly and clear. And they even take the time to show me what makes a good password so I don’t have to guess six times.
</p>
<p>
<strong>Don’t waste time.</strong> Your time is expensive, but your users’ time is what matters most. You work at an incredible scale—and if you’re lucky, hundreds of thousands of people will read your work. You have more readers than most published authors! Be proud and careful with that power.
</p>
<p>
As Paul Ford says in <a href="https://contentsmagazine.com/articles/10-timeframes/">10 Timeframes</a>:
</p>
<blockquote>
<mark class="highlighter-color-2">“The only unit of time that matters is heartbeats. The time you spend is not your own.”</mark>
</blockquote>
</section>
<section id="write-iteratively">
<h3>5. Write iteratively.</h3>
<p>
You write code iteratively, so why not the rest of it? It’s okay if your interface writing isn’t perfect. But you better believe that you need to go back and clean up those strings before you go live.
</p>
<p>
One way to make that easier is to organize your code. Maybe you have a mailer folder for all of your emails or an errors folder for your error messages. You can do that in Ruby with your localization file. Make it easy for yourself and your team to keep things up to date. If you’re writing QA tests, please don’t hard code strings into them. Start with the assumption that the copy will change.
</p>
<p>
Writing is a messy, iterative process. Here's an example of what a writing plan looks like for me. This is an illutration by Alvin Diec from the book I coauthored, <a href="https://www.nicelysaid.co/"><em>Nicely Said</em></a>.
</p>
<p>
My process begins with the questions I mentioned, and then I sketch a rough outline like this. Next, I write a few variations. Here are some quick examples of a button label:
</p>
<ul class="circle-container_content-style-three">
<li>Save</li>
<li>Update</li>
<li>Send</li>
<li>Submit</li>
<li>Post</li>
<li>Publish</li>
<li>Comment</li>
</ul>
<p>
From here, I usually narrow it down to two or three options. Writing copy variations makes it easier to come up with something good, and it also gives you a place to start when you’re A/B testing. Don’t be afraid to test calls to action and navigation labels. Those little details add up to huge improvements in conversion and engagement.
</p>
<p>
You should <em>never</em> test something you wouldn’t ship. Don’t throw your principles out for numbers. Your readers don’t know a test from a normal piece of text. If you’re not comfortable with a particular phrase, it doesn’t belong in a test.
</p>
<p>
Lastly, remember the text can change. Don’t try to perfect it the first time. Keep refining it. Make it clear, and then make it clearer. Find a way to build a system that works for your readers and your business.
</p>
<p>Thank you.</p>
</section>
</section>
</article>
</main>
</body>
</html>