Interface Writing: Code for Humans

Introduction

The web and the world are full of instructions. Everywhere you go, signs and people are telling you what to do.

• "Walk. Don’t walk."
• "Follow me please. Stop. Hang on. Please stand clear."
• "Fasten your seatbelt. Read this."
• "Do this"
• "Take this. Buy this. Find us on Facebook. Please enter your name."

You get the idea. So bossy.

Interface Writing

Think about the app you’re building right now. 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?

Whatever you’re building, you need to think about the content in the database and the instructions around it. I call those things interface writing. Some people call them microcopy since they’re usually short.

• buttons
• notifications
• erros and alerts
• forms
• in-app disclosurers
• links
• navigation
• product tours
• settings names
• tooltips
• transactional emails

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.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.

With clear instructions and a warm tone, you can help them find what they need quickly without having to ask anyone for help.

Strings

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.

We used to have this program called Dr. Sbaitso, which you may have heard of. It was a computerized psychologist slash artificial intelligence program designed to show off sound cards, but I thought it was a game and used to play with it for hours.

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.

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.

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 parity error.

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.

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.

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.

From a high level, these are my goals when I’m writing strings:

• Be clear.
• Be kind.
• Be careful.
• Be honest

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.

Every Form is a Question

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?

Here are some examples of things you might be asking:

• How can we help you?
• What are you interested in?
• What do you think of this product?
• Do you need this in a hurry?
• Where do you live?
• Are you married or not?
• Where are you right now?
• How did you hear about us?

You probably wouldn’t ask a complete stranger these things without a conversation or consent.

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.