The openSUSE Design System uses cookies to help us learn more about how we can improve the design system.
Learn more about our cookie policy

Edit preferences

UX writing guide

UX writing focuses on helping users achieve their goals with language.


General writing tips

check_circleDo
  • Front-load important information and write for how much people want to read

    Users read a given amount of text after which they only scan for seemingly important phrases or words. Include important information up front and only write as much as users are willing to read.

  • Use lists when needed

    Any sentence containing 3 or more items separated by a comma should be turned into a list.

  • Format long-form content properly

    Make long-form content more scannable with structural elements (labels, headers).

  • Don't use "here"

    Embed your links in clear, descriptive language.


Best practices

  • Clear

    Often, the issue at hand is due to software problems, not people problems. Pay attention to verbs. A verb is an action word, it tends to be the most powerful part of your sentence. In a perfect world it will relate to some action to the user.

    For clarity we remove the technical terms and put the action in the context of the user.

    cancelBefore

    Failure

    An authentication error has occurred.

    Ok
    check_circleAfter

    Sign-in error

    You entered an incorrect password.

    Ok

    This is important when you’re writing a product announcement or an app update. Currently, the focus is on the technical specs of the new feature you’re releasing. Focus instead on the new action that people can perform. Jargon free messaging offers context.

  • Concise

    Concise doesn’t only mean short, it means something closer to efficient. When we are writing concisely, we look at our message and make sure every word on the screen has a distinct job.

    cancelBefore

    Sign-in error

    You entered an incorrect password.

    Ok

    The above is a common problem in product writing. We don’t need a header here. Because the design field shows some pre-existing text field, we feel we need to fill it in. You should avoid this, when you can instead practice content first design.

    Content first design makes sure your visuals are inline with what you’re trying to say. Not the other way around. Try not to jam your message in boxes that weren’t meant for them.

    check_circleAfter

    You entered an incorrect password

    Ok

    Here we’ve removed the header. As research suggests, most people don’t read every word that’s present on their screens. They tend to scan.

    We know that people’s eyes follow an F shaped pattern as they read over the screen. They read the first line, the second line, then start skipping down the page catching only the first or second word of each sentence. For this reason we keep our text not only concise but also frontloaded.

    Frontloading is the practice of putting your important concepts first. This is done so people’s eyes catch those important words as they scan through the page

    cancelBefore

    You entered an incorrect password

    Ok

    Above, most of the words are at the end of the sentence. We can fix this by flipping it around as shown below.

    check_circleAfter

    Wrong password

    Ok

    You won’t always be able to do the above. The principle will always hold true and you can use it anywhere you’re writing for screens. Keep the most important text up front and then ruthlessly edit what comes after it.

    cancelBefore

    Sign-in error

    You entered an incorrect password.

    Ok
    check_circleAfter

    Wrong password

    Ok

  • Useful

    The call to action (CTA) guides people to their next step. You want your text to help people get where they want to go. For this reason the call to action needs to resonate with what people want to do. Here ‘OK’ is not a good call to action.

    ‘Try again' is a good option instead. This isn’t all we need. We need to give them an option if they’ve forgotten their password. If they forget their password and their only option is to ‘try again’, it’s very likely they’ll get frustrated.

    Paying attention to writing and the people you’re writing for is very important. It can uncover some of the basic functions that your app or website needs to offer. If you don’t think of those edges cases and write for them, you might see a drop off in usage.

    cancelBefore

    Wrong password

    Ok
    check_circleAfter

Find the right balance

Good UX writing is not a science. These three principles are not always in harmony. There’s a kind of tension between them. They’re competing with each other.

Cleararrow_forwardjargon-free, offers context

Concisearrow_forwardeconomical, frontloaded

Usefularrow_forwarddirects next action

When we made the text clear it’s still pretty long, and not so scannable. When we made the text concise, it made it shorter but at the expense of some clarity. Finally when we made the text useful it became longer and less scannable.

Consider your users context and you’ll find the right balance between these principles. Think about what they want to do in the moment.

Brand voice
UX writing principles
Thriving

How you say it

Surviving

What you say