Publishers of technology books, eBooks, and videos for creative people

Home > Articles

  • Print
  • + Share This
This chapter is from the book

Be clear

Writing is almost always about clarity. Of course you want to be clear! But if you’re under a deadline, it can be hard to spot what’s confusing to readers. Here are a few practical tips.

Remember that you’re the expert

Don’t assume that readers will understand what you’re writing about. You know your business and your website better than they do. Invite them in as if you’re striking up a conversation or telling a story. You don’t have to dumb things down, but you do need to help readers skim and follow along. Think about what you’d tell a friend or a neighbor if they were learning about the topic you’re covering.

Keep it simple

If there’s a shorter word to say what you mean, use it (Table 4.1).

Table 4.1 Use short, simple words

Longer

Better

compose, author

write

discover

find

incentivize

encourage, reward

objective

goal

obtain

get

optimize

improve

purchase, acquire

buy

retain

keep

utilize, leverage

use

If you have to use a technical term that people may not recognize, briefly define it or explain it in plain language.

Keep your writing as close to speech as possible. One way to do that is to read your work aloud and see if it sounds like you. For example, do you ever hear people say “inimitable” or “natch” in person? Yikes. If it feels forced, rephrase it. Another way to write like you talk is to use contractions, which crop up naturally in conversation.

Be specific

If you’re writing instructions for a series of steps, go through the steps yourself and write down the names of links or buttons exactly as you see them. Be explicit in what you’re asking the reader to do.

Avoid vague instructions:

  • Update your settings to receive fewer communications from us.

Instead, include specific labels:

  • To receive fewer emails, go to Settings > Email Notifications.

Names and labels improve clarity like signs on a highway. Show people how to get around by adding these details. This is especially important for links to articles, headings, and help content. Consider these questions as you write:

  • What is the reader trying to do?
  • What does the reader need to know?
  • What’s missing?
  • What happens next?
  • Is this topic covered somewhere else?

Tell readers what to expect and guide them through the process. Don’t stop at a basic confirmation:

  • Your order was successful.

Instead, add details about the order:

  • Thanks for your order. You’ll receive an email confirmation within a few minutes. [View Order] [Print Receipt]

If something goes wrong, politely explain what to do next, whether it’s reading an article, resetting a password, or asking for help. Including buttons and links can help you with that.

Be consistent

Use names and labels consistently. If you refer to notifications in one place, call them notifications everywhere else—not push notifications, instant notifications, real-time alerts, or messages. Being consistent and being repetitive aren’t the same thing. Consistent names reduce the number of things your readers have to remember. Being consistent helps people understand the different parts of your website and shows them where to find what they’re looking for. As an added bonus, consistent terms improve usability and reduce translation costs.

You should also be consistent with how you capitalize headings and subheadings—whether you decide to use title casing or sentence casing.

Be careful with pronouns, too. Some websites are confusing in this way. They refer to the reader as you in one place and me in another. Here are a few common examples from headings and links:

  • About us
  • My account
  • Enter your comment
  • Your orders

Who’s us here? Generally, us and we should refer to your company, with our referring to things belonging to your company. This is where my is especially weird. Who’s me here? The reader or the company? One way to avoid this awkwardness is to avoid pronouns in the first place:

  • About
  • Account
  • Enter a comment
  • Order history

Otherwise, we recommend calling the reader you to keep your writing conversational. This is definitely a style choice, but you should be consistent one way or another to avoid confusion.

Break the rules thoughtfully

Most of the time, your writing should fit in with your house style or the style of the publication you’re contributing to. But every now and then, you’ll need to break the rules. It’s common for web writers to break traditional style conventions, because some rules don’t read well online. For example, most style guides say to spell out numbers up to ten, but digits usually work better on the web since readers are scanning. Another example is how you refer to people after introducing them. Traditionally, you’d use the person’s last name, but people don’t talk like that in person, so it’s a good rule to break.

As you write, keep the appropriate rules and style conventions in mind. Be careful not to confuse or distract the reader. When in doubt, talk about the issue with an editor, rephrase the sentence, or break the rule thoughtfully. If you find yourself breaking the same rule regularly, it may be worth updating your style guide. (We’ll talk about style guides and other exceptions in Chapter 12: Style Guides.)

Avoid abbreviations and acronyms

It can be tempting to shorten words to save space, but clarity should always come first. As an example, security code is a little longer than CVV, but it’s easier to understand at first glance when you’re talking about credit cards. If you have to use an acronym, briefly define it in plain language on the first mention.

If you’re working within character or word limits, you may need to shorten words occasionally. Here are a few commonly accepted examples:

  • Dates: Sat Nov 22
  • Times: 3h5m, 3hr 5min, am, pm
  • Places: USA, UK, EU, JP, CA
  • Numbers: $20M, 45 ft, 60 m, 60 mi
  • Technical terms: 3G, LTE, EDGE, Wi-Fi
  • Formats: CD, DVD, JPG, GIF

If you decide to use abbreviations, look out for confusing ones, especially those that can refer to both states and countries. For example, CA could be either California or Canada. Use abbreviations sparingly, and add approved ones to your style guide.

  • + Share This
  • 🔖 Save To Your Account