Sample Chapter: Writing Is Designing

December 2, 2019

This is a sample chapter from Michael J. Metts and Andy Welfle’s book Writing Is Designing: Words and the User Experience. 2020, Rosenfeld Media.

Chapter 3: Creating Clarity: Know What You’re Designing

Cover: Writing Is Designing

One thing many writers have a strong opinion about is the serial, or Oxford, comma. If you’re unfamiliar, it’s the comma that comes before the and in a list, as in “this book is about writing, designing, and the user experience.”

Every major style guide on writing takes a firm stance. (The Associated Press Style Book, for example, is against using it, but the The Chicago Manual of Style is for it.) It’s common to see writers declare their personal stance in their Twitter profile.

“Without it,” proponents cry, “There will be chaos! No one will know to what we’re referring in lists!” Then they point to an example of an author dedicating their book to “my parents, Beyoncé and God.”

Champion Advertisement

On the other side, the anti-serial comma faction pipes up. “But that’s why we have context clues! We all know it’s implausible for someone to believe God is one of their parents! Plus, we could just reorder that list to ‘God, Beyoncé and my parents’! That comma is redundant and therefore unnecessary! We must be concise!”

As with all strong opinions about subjective things, the answer lies somewhere in the middle. Context matters. If you’re writing a legal document, where precision is key, a comma might mean—and has meant—the difference between winning or losing a lawsuit.

If you’re writing a newspaper article, with a finite amount of space and a thin column of text, it’s probably not needed. That’s why newspapers follow the The Associated Press Style Book, which focuses on brevity and concision.

Whether or not you’re using the serial comma doesn’t matter so much as how much clarity it adds to your message. And to understand that, you need to understand the context of your message.

Know What You’re Writing

While your team may not care about words as much as the serial comma crowd, it’s important to help everyone understand the role they play.

In the past, ad copywriters worked with designers and account executives to synthesize the product’s value proposition or feature messaging into copy. And no copy was more important than that clever tagline—it was the hook that drew readers’ eyes to the ad. As you can see in Figure 3.1, [in a 1960 ad campaign for the Volkswagen Beetle, copy plays the largest role in hooking and captivating the reader.]

Copy hooks and captivates the reader — Figure 3.1—Copy that hooks and captivates the reader

But when you’re writing for a digital interface, it’s different. Are you trying to educate a user? Are you trying to intrigue them into exploring more features? Charm them into upgrading to a premium tier? Or are you trying to make a complicated feature simpler?

Bring the Clarity

Writing is designing, so your primary goal should be to bring clarity to your users. Clear writing helps users understand what’s happening with the product and what it means for them.

To bring clarity to your users, you have to start by bringing clarity to your team.

If your head is filled with questions about what your product or project is, you may feel embarrassed. Shouldn’t I know what I’m writing for? Look at all these other people—don’t they know what they’re making?

Well, it may surprise you, but no, there’s a good chance they don’t. Sure, they know what features they’re building or what interface they’re simplifying, but often, especially with enterprise software, even the project lead hasn’t seen the full breadth of the site or application.

But words have a way of facilitating clarity. Here are some examples of things you may need to write for a product, along with questions you can ask to understand them more clearly:

introductory screens and onboarding—Who are our users? Why should they care about this product? How does it make their lives better? What bits could be confusing?
billing systems—When does the first payment happen? When do payments renew? What methods are accepted?
notifications—What’s the goal of this notification? What is our team being measured on? How does this help the user?

These are questions that everyone may have in their heads, but writers are sometimes the first to ask them. It’s hard to write about something without understanding it. While you need clarity if you want to do your job well, your team and your users will benefit from it, too.

Design teams use software like Sketch or XD to show what they’re designing—and those tools are great—but it’s easy to get caught up in the details. There are sliders for rounding the corners of buttons and color pickers for precisely choosing which shade of blue they are, but there’s no selector for figuring out what you’re working on or why it matters. It’s an open world—a blank slate. It’s a job for words.

A lack of clarity isn’t just frustrating for members of the team, it’s also expensive. When everyone has a different understanding of the problem you’re trying to solve, they may ship a feature that isn’t needed or put up a Web page that has to be revised a few days later.

So before you start writing button labels, or working on voice and tone guidelines, use the world’s most underrated and effective design tool: a text editor.

Start by writing. Write without constraints or voice or tone.

Detail what the interface should say. If you do that, you’ll understand better how it works. Words are the key to unlocking meaning, and because of that, it’s perhaps the most powerful way to align a group of people with different perspectives, agendas, and preferences to a project.

Understand Implications

If you design a digital product without focusing on the words, it’s easy to avoid thinking about the message that it sends to its users. When you take responsibility for the words in an interface, you are the last line of defense against manipulative practices, misinformation, and jargon. Thinking about the language intentionally means that you’re also thinking about its ethical implications—from how it could exclude people to the way it’s used to shape and influence behavior.

In her book Technically Wrong: Sexist Apps, Biased Algorithms, and Other Threats of Toxic Tech, Sara Wachter-Boettcher writes about a smart scale that emails you when you step on it. By default, the message it sends when your weight is higher than it was before is disappointed, but encouraging: “You’ve gained X pounds. Better luck next time!”

To someone who is trying to lose weight, the message is fine. Harmless, even. But what about someone with anorexia, or a child, even, who’s trying to gain weight? It’s an eye-rolling message at best and harmful at worst.

Somebody had to write those emails. If they were thinking systemically about the words they were writing—not what the words should be, but also how they fit into the larger system of words the user sees—they might identify the cases where users aren’t experiencing what the company thinks they’re experiencing. Of course, even if the writer understood these implications, the organization they work for may not be structured to allow them to flag potential concerns and change course once the project is underway. Large, siloed organizations tend to be bureaucratic and process driven, and aren’t particularly adept at changing strategies downstream. It could be that this writer wasn’t empowered to raise this concern.

That’s why it’s important to collaborate with your team on the words as soon as possible, while a project’s scope is still new and malleable. It’s much easier to change wording—or even the product’s message—when it’s written on a white board or a Word doc than when it’s coded into an interface.

Recognition and Recall

Being clear is challenging on its own, but the real challenge is to do that over and over again, throughout the experience you’re working on.

The Nielsen Norman Group, an organization that conducts user experience research, has a list of ten important usability heuristics for user interface design. (A heuristic is, broadly, a technique that allows someone to teach themselves something.) One heuristic that’s key for writers to understand is “recognition over recall”—in other words, make plain the object, action, and options a user has, so they don’t have to remember it. One of the best ways—perhaps the best way—is to do that with words—as in a citation.

The study digs deep into memory retrieval, particularly the concepts of recall and recognition:

Recall, a process your brains use to retrieve information from your memory, is how you remember things like user names, passwords, Web addresses, and other open-ended prompts.
Recognition, on the other hand, draws from many more overt clues to allow you to make a decision. An example might be a button with a clear call-to-action, for example, or a list of menu items. Each of these elements gives you the cues you need to recognize an option, make a decision, and ultimately accomplish your goal in an interface.

For example, if you label an action Delete in one area and Erase in another, the words may mean the same thing, but now the user will have to pause whatever they are doing and think about it. Choosing one option—along with rationale to back up your decision—and using it consistently will help your users recognize the action when they see it, while being assisted by whatever they’re able to recall from the last time they used the action.

Visual layout and presentation is important for recognition, but the words you use are especially important. The clearer and simpler they are, the more you give the user cues to borrow from their own understanding and experience to move forward.

Lightening the Cognitive Load

Making things simple for your users can be a big challenge. One person who is up for that challenge is John Saito, a product designer at Dropbox, a San Francisco-based software company that sells cloud storage services and creative tools. Like many writers working in user experience, his path wasn’t a direct one: he worked as a localization writer, a help documentation writer, a UX writer, and more. Early on, as a UX writer, he read Don’t Make Me Think: A Common Sense Approach to Web Usability, by Steve Krug.

“It completely transformed the way I think about words,” Saito said. “The basic idea is that you need to try to make the user think and read as little as possible. That’s the only way to have a fighting chance at people even reading your content and digesting it. It’s always in the back of my mind.”

This leads him to work as hard as possible to reduce the number of words and reduce the number of choices that are presented to a user at once.

“If, as the writer, I have to think about the words for more than two seconds, I know it’s not good copy.”

Saito said that, when he was in college, he studied cognitive science—how people think about the world. Soon he found himself in a class with George Lakoff, a prominent cognitive linguist, and was digging deep into the idea of metaphor in language.

“It turns out the way in which we understand the world is almost entirely through metaphor,” Saito said. “If you closely study the words we use, you can trace it back to metaphor.”

When it comes to design, Saito says, everything is a metaphor.

“The gestures we use—clicking, tapping, or swiping, they’re all metaphors of something we’d do in the real world. And the icons we use—floppy disks for saving, and the cutting and the pasting. All metaphors.”

Words are the same. You can use metaphors in terms, like inbox and timeline, or in actions like copy and paste, as Saito mentioned. Some products are built entirely on metaphors, like Photoshop. It’s full of tools related to photo editing and compositing, with its roots in darkroom photography and tabletop editing.

Note: John Saito on Metaphors

Metaphors help people make sense of your product. Saito says there are a couple things to keep in mind if you’re developing a metaphor:

Does this metaphor actually describe what the user is trying to do?
Don’t make me think: Is it common enough for a broad understanding, or is it too localized for my user base to understand it?
Is it internally consistent, or does it conflict with other terms and actions in my product?

There’s nothing wrong with these metaphors, as long as your audience can still borrow understanding from the original concept. Some take on a life of their own. (For example, we still say that we’ll dial a telephone number, even though the majority of people alive today have never used rotary phones with a literal dial.) Some metaphors lose their meaning over time. (Many users today have never seen a floppy disk and don’t understand how it means save.) And some products evolve past their original metaphor and become internally inconsistent. (For example, Photoshop has a magic heal brush that uses intelligent algorithms to erase elements from a photo, extending well beyond the capabilities of an analog photo shop.)

How Metaphors Influence Behavior

While a metaphor often helps users, it can sometimes make things more challenging. Voice assistants and chatbots rely on the metaphor of conversation to work, which means that you may have to design extra features just to accommodate how users think about the interface.

Figure 3.2 shows one of the first conversational interfaces I designed. It greeted users and then asked what they needed, which is exactly how you’d expect a human providing chat support to act. Users would greet the bot back to be polite, but [the chatbot was expecting users to describe their issue, and the conversational metaphor prompted them to greet the bot instead.] This meant that we needed to design a new opening message that didn’t prompt this type of response and helped our users faster.

Figure 3.2—This bot expected users to describe issues, not greet it

In this case, the metaphor of conversation changed user behavior, and we had to make sure it didn’t go too far past what the technology was capable of.—Michael J. Metts

Finding the Balance Between Precision and Concision

When you’re building a complicated product, often you’re faced with a complicated message and enormous constraints. One time, I was working on a search results page for a social networking app. The directive I was given was that this particular section of the search results showed profiles that matched the following parameters:

Here are profiles matching your query, showing:

friends
friends-of-friends
those who have written posts that friends or friends-of-friends have liked or commented on

Impossible. I immediately realized there was no way I was going to be able to convey all of these nuances in four or five short words. After several iterations and frustrating writing sessions, I returned with this: people connected to you.

This was the absolute best I felt I could do under the circumstances. I wasn’t capturing a lot of nuances, but if we painted with broad brush strokes, this made sense. I turned it in. It was concise, and it fit the space allowed.

I didn’t hear about it again until an engineer reached out to me. She was starting to put this functionality together, and she had major objections with that heading.

“This tells the user nothing about the functionality of this module! We need to be more precise,” she argued.

I countered: “This module is inherently too complicated, and there’s no way to capture that precise functionality in a short string of text! We either need to be concise, or we need to simplify the functionality.”

We were at an impasse. This was an extreme example of when a message was too complicated to properly express in copy—and to stay within our constraints, much of the message was lost. We often have to find a balance between being precise and concise, which can sometimes be in conflict with each other. [Figure 3.3 shows how you can explore the balance between concision and precision across a spectrum of messaging to find what fits a given context.]

Figure 3.3—Balancing precision and concision

That’s a situation where we couldn’t solve it with words. We had to go back to the drawing board to revisit, fundamentally, what the module was trying to be.

This module never shipped, but it did eventually evolve into separate modules—with simpler, more direct functionality.—Andy Welfle

Clarity Is in the Eye of the Beholder

It sounds like a no-brainer, but it’s important to use language that your audience understands. Your users should be at the center of your writing process, and that’s especially true when it comes to the language you use in an interface. It should make sense to them, and ideally, include the words they already use. In addition to the research methods in Chapter 2, “Strategy and Research,” here are a few ways to do that:

online discovery—If you find your users online, you’ll also find a wealth of information about how they communicate. Maybe the people who use your software hang out in certain Facebook groups. If you’re working on a mobile app, check the reviews to see how your users describe it and what they use it for.
search analytics—If your product or site has a search feature, analyzing what people search for doesn't just help you understand the words they use, it can also help you identify areas for improvement within your product. Often, a few of the top search terms reflect the majority of what people are searching for.
communication analysis—If you work for a large company, you’ll often find information about your users’ language in places like call-center logs or support tickets. Build relationships with those teams and see if they can share their data. By breaking that data down, you’ll begin to see the most common patterns emerge, and you’ll be able to incorporate what you found into your writing. Data scientists can be an incredible resource in situations like this if you have access to one.
coworkers—Depending on where you work, chances are, there’s a team or two that talks to your customers on a regular basis. Maybe it’s the sales team. Maybe it’s customer support. In any case, talking to those coworkers will not only make them feel appreciated, but will also teach you about your users and the language they use.

When working with customer data like this, take care to do it ethically. You and others don't need to know the names of the people involved or be privy to their private information. Learn about your users—don't spy on individuals.

This is a critical step, because you may find that the language your users use is quite a bit different from the language your team was planning to use. You can help your team see things from your user’s perspective.

Writing with Plain Language

Most of the time, if your product is for the general public, you’ll find that the best course is to use plain language.

That’s harder than it looks: Unless your company has a profoundly user-focused culture—and let’s face it, almost every company could be a bit more user-focused—it’s easy to get caught in a bubble of business and software development jargon. From customer service systems that ask if your issue has been resolved—do real people ever ask each other to “resolve issues”?—to technical errors that are only meaningful to the people that wrote them, there is plenty of opportunity to make language more understandable and simple.

Maybe you’ve managed to stem the tide of buzzwords and filler phrases like “go ahead and…” and “at this time…” but there are still many terms and phrases that won’t make any sense to the user.

The Nielsen Norman Group conducted a usability study showing that plain language benefits all readers:

It’s concise, helping users understand a concept quickly.
It helps those who speak English—or whatever language you’re writing—as a second language.
It makes your language more searchable and improves your search engine optimization (SEO).

These points can help you convince marketers and decision-makers to simplify the words in product marketing and onboarding experiences.

Plain Language in the U.S. Government

It seems hard to believe, but governments are doing some of the best work when it comes to writing in plain language. In 2010, the United States federal government passed the Plain Writing Act that provides a clear definition of plain language:

“Writing that is clear, concise, well-organized, and follows other best practices appropriate to the subject or field and intended audience.”

It also, just as importantly, mandates that all government offices and services write plainly and according to their guidelines.

And while different offices and administrations have achieved varying levels of success with using plain language, there’s one in particular that builds it into their DNA.

18F is an organization within the General Services Administration of the U.S. government that builds products, collaborates with other agencies, and serves with a mission to deliver great, useful digital products to the government. In addition to exceptional products, they create and publish standards and guidelines. The 18F Content Guide is one such document that can help with many products and organizations well beyond the government.

One of the best pieces of advice their guide gives is powerful and should be the principle underlying everything you do: “Do the hard work to make it simple.”

Here’s what they say about that:

“Help the reader follow along. Break instructions or processes down into individual steps. Use short, simple sentences with words people use in everyday conversation.

Refer to navigation labels, buttons, and menus as they appear in the app or Web site. Verify the spelling and capitalization as you write. Be specific.

Instead of: Open a new meeting invitation.

Use: In Google Calendar, [click] Create.”

Using Jargon: Your Results May Vary

There are so many different kinds of software in the world, and the threshold for plain language can vary wildly depending on the app. Are you designing something for a very specialized audience, like construction equipment purchasing managers? Or are you designing for the general public, like an event-ticketing app? If UX writing is a brand new discipline at your organization, and you don’t have the capacity to go deep on domain expertise—don’t worry, neither do most of us—you may have no insight into what words your users understand and use.

Facebook, for example, takes great pains to distill their language into the simplest form possible. That’s evident in the names they give the core components of their ecosystem, like Pages, Groups, and even complicated, advertising metaphors like conversions and engagements. This makes perfect sense. They have a user base of more than two billion monthly active users, and their software is localized and translated into more than 100 languages.

But as a word of warning: Make sure that the jargon you do use is truly widely accepted and used in your users’ industry. As we discuss in Chapter 2, research is a great way to find out how professionals talk. Sometimes, a short conversation with professionals about their work is invaluable to writers and designers alike who are trying to build products for them.

The best way to solve this would be to put the shortened copy, along with a prototype, in front of real users! You’ll learn pretty quickly if that message confuses them, or if they have enough context clues to make an informed next step.

Good Jargon

Plain language is almost always the right way to go, but there are exceptions.

I once designed software that modeled machines and helped engineers size and select the components they needed to build it.

For example, they could be building a conveyor belt that moved tomatoes up an incline, through a washing mechanism, then placed them individually in cartons and labeled them. This software would allow the engineer to enter factors like the angle of the incline, the load on the conveyor belt, and the required speed, and then size the right motors and drives needed to build it.

In this case, it wouldn’t make sense for me to use the interface to explain how load affected incline or what those terms meant. In fact, that would just have slowed them down as they used the tool throughout their workday. In the end, this interface didn't make sense to anyone but its users. However, it helped them size the parts they needed quickly and easily.—Michael J. Metts

In Practice: Simplifying the Language of a Confirmation Dialog

Let’s look at a warning dialog from an interface used by companies to assign software access to users. In this scenario, the admin, or administrator, is turning off the feature that allows their users to share links to their work publicly—perhaps the company’s privacy policy changed, or someone shared a link that wasn’t meant to be shared and the company is cracking down. But when they turn off that public link-sharing feature, they may not realize that all previous publicly shared links are turned off retroactively. [Figure 3.4 shows example dialog from an enterprise software company’s admin console warning the administrator about a complicated consequence of changing role permissions.]

Figure 3.4—Warning an admin about changing role permissions

This is a mouthful. Let’s say that you’re trying to edit this warning down to be more effective and to lighten the cognitive load on the user. It’s complicated, but you can start by breaking down the copy into the bits of information included. This really gives you a deeper understanding of the message that’s being conveyed, front and center. You’re probably already doing this in your head, but let’s do it on paper:

The action you’re taking will limit sharing to users in your organization.
Users can only share and collaborate with people from certain approved organizations—represented by domains.
Users will not be able to create public links to their work.
If you turn this setting on, all existing public links will be deactivated.
Are you sure? Yes / No

This lets you sit back and really soak in the message. Look at all these messaging points you’re trying to hit into one confirmation dialog.

Dig into the Flow

Since writing is designing, you really can’t just edit this message in isolation. You need more context around where a user is coming from and what is prompting this message to appear. If you don’t have access to the prototype or a design file for this message, ask the designer or product owner you’re working with. It’s important to see what the user saw before this message. [Figure 3.5 shows the Asset Settings screen, which let the admin select the sharing privileges for the users in their organization, following which the confirmation dialog shown in Figure 3.4 appeared. In this figure, the option that disallows public sharing is selected.]

HowOld.net — Figure 3.5—Assets Settings screen

Prioritize the Message

Now that you understand a little bit more about this interaction, you can decide which information is more important for the user to see by re-ranking your messaging points. In this case, it’s really important that the admin knows that any existing public links will be turned off if they proceed with this change, so let’s move that from the bottom to the top of this message.

Put the Question First

Next, see where you can consolidate. Since the confirmation of this confirmation dialog is really why you’re here, reflect this in the title since that’s the most important.

Limit sharing to domain users?

And because UI [(User Interface)] is a conversation, you need answers for the user to give that reflect the question being asked in the title: your button set could more accurately reflect the question being asked as a simple Yes and No instead of the jargony and mismatched Enable and Cancel.

Trim the Fat

Next, look at that first line of text in Figure 3.4, explaining what this sharing restriction means. Users just saw this in a previous screen, as seen in Figure 3.5. And since this confirmation isn’t about education around types of domains, you can trim that out.

De-jargonify

And finally, there’s some jargon we can trim out to simplify the language.

Enable = Let
Deactivate = Turn off

Until finally, you’re left with a concise, clear confirmation dialog. [In Figure 3.6, you can see the original confirmation dialog on the left; the edited dialog on the right.]

Figure 3.6—Original and edited confirmation dialogs

[The edited dialog is] shorter, by more than half, and much easier to read. This really lets the message stand out and be clear about the consequences of taking this action.

Finding What’s Right for You

The way you achieve clarity can vary widely, depending on so many things—the functionality of your app, the type of user you’re targeting, the context they’ll have when using it, and so much more. Just as a serial comma doesn’t make sense in short form journalism, but is completely necessary in legal writing, clarity is a moving target. As with everything in this book, it’s super important to test your messages and interfaces with users.

Discount for UXmatters Readers—Buy Writing Is Designing: Words and the User Experience online from Rosenfeld Media, using the discount code UXMATTERSWID, and save 15% off the retail price.

In Sample Chapters | Writing User-Interface Text