How to write user help text: quick tips and resources

Unless you’re building a website just for people to look at, you need to pay a little attention to your user help text. Well-designed field labels, button titles, and tooltips make a big difference to your users.

User help text: better if you get it right first time...

User help text: better if you get it right first time...

Why user help text matters

Pretty much everyone who builds a website or app is aiming for some level of interaction. The goal is to get users to click, download, or buy something.

If you want users to do stuff, you need to tell them what to do. And depending on the purpose of your site, those instructions might be quite complicated.

Frustrated users = non-returning users. Or lots of time spent on support. Or lots of tidying up when users do things in unexpected ways. Or all the above.

So it's in your interest to write the best instructions you can.

Start writing help text as soon as you can

If you’re still at the sketching stage, I wouldn’t worry too much about detailed help text. Concentrate on making the layout as useful as possible so users can find their way around without too much help.

Once you get on to wireframes (i.e. layouts in a graphics tool), start adding realistic text. Write labels for your buttons and fields. If your form is going to have an intro for users, add that too.

I get fed up with reviewing designs full of 'placeholder text', and 'hint goes here'. It's useless for testing. If you're testing wireframes that only contain boxes and lines, you may as well have stuck with a sharpie.

Which brings me to…

Test early and often

Users don’t always think as you do. Help text that makes perfect sense to the project team can fail utterly for users.

If users struggle with your help-free wireframes, it’s easy to assume it will all be okay once you add a load of tooltips. And sometimes it is. But quite often it isn’t. You end up having to rework an entire form because no amount of help text rendered it intelligible to users.

Keep instructions short

In my experience, people don't read lengthy instructions. Even a couple of lines will send them skipping on to the next interactive thing - a field, a button, whatever.

If you need a paragraph or two to explain the task, start by simplifying the task. Then go back to writing instructions.

If you need to provide detailed instructions for a complicated task, then try to break them up. Put the instructions for each field right next to it. And don't try to explain every single scenario. Include the information that every user will need, and put the rest in your help centre.

How experienced is your user?

Are you writing for beginners, improvers or experts?

If your user is going to visit your site rarely, or they are new to the task at hand, consider treating them as a perpetual beginner. They will need a lot of help.

If you write the same level of help text for tasks that users often do, they will get bored and start skipping. So when you do need to tell them something, they aren’t paying attention.

For instance: consider tax return forms. We only fill these out once a year, and they change from year to year. The instructions for each field are pretty detailed. These forms expect us to be clueless - and that's fine.

Right at the other end of the spectrum are checkout forms. If you wrote instructions for a checkout page at the same level as a tax form, you'd drive your user crazy. Even if users don't visit your site that often, they visit checkout pages all the time. Simple labels will be enough to get through the process.

Once in a while, you will get a user that doesn't have a clue. So you provide more information on the help centre, and you're on standby in case they get stuck and ring you. But for these kinds of tasks, you should assume most users know what they are doing.

Use the right tone of voice

Even if your user is a total beginner, they are still a grown up. They probably don't want to be spoken to like a toddler.

The user help text that inspired this post. Great job! (Not).

The user help text that inspired this post. Great job! (Not).

And even if you're targeting a young audience, you can assume they are at least teenagers. I never met a 13-year-old that like to be talked down to.

Tip: in the UK, where I live and work, the digital age of consent is 13. If you're offering a site that interacts with users younger than that, you should probably be seeking professional advice. The Information Commissioner's Office is a useful resource for UK designers.

A useful guideline is to write for a smart 14-year old. That usually results in clear but still friendly instructions that work for all age groups, including adults. If you can find a smart 14-year-old to test it on, so much the better.

Check your work

Read it, and read again. Get others to read it. Start your colleagues before inflicting your help text on users.

Spelling and grammar mistakes are embarrassing so get rid of as many as you can. (Though accept you will miss some - there are probably at least three errors on this page. Remember to thank users nicely when they point them out.)

Because I work alone, I use Grammarly to help me get this stuff right. It's smart enough to point out where the sense is unclear, as well as catching fundamental errors like misplaced apostrophes.

But don't stop at typing mistakes. Check people understand the meaning of what you've said. Get them to explain it back to you in their own words. Test them with questions like 'when will your package be delivered?' or 'who will I share your data with if you tick this box?'.

Keep trying till you get it right

However much you test, you'll still find mistakes when you put the page in front of actual users. Keep an eye on emails and calls to your support team. Over time, patterns may show up, highlighting areas for improvement.

So it's useful if your app or site allows you to change instructions easily.

If you're using a platform like Squarespace or Wix, you can change anything you want. If you realise that a button or a label is confusing users, go ahead and try something else.

If you're getting a custom site built, talk to your developer about this. See how much flexibility they can provide on changing instructions. If you're getting a support contract with the same developer, see if they will include small text changes as part of that deal.

It's not always possible to change text easily on a bespoke site. If you need to get it right first time, spend extra time testing with users early in the project.

How to test user help text

If you're using a site builder like Squarespace, you might decide to go straight in and build the site there. Then you can test the real thing with users.

This approach can take quite a lot of work, though. And if it's the layout that's causing issues, rather than the text, it can be hard to change things around and try different options.

Most designers start by sketching the layout with pen and paper, to get the basic position of buttons and fields. You can get a lot of feedback from testing at this stage.

Photocopy your sketches and ask your tester to work with the pages as if they were using your website. Ask them to point where they want to click, and write on the page instead of typing in the fields.

Examples of hand drawn mockups for testing user help text. We found these instructions were way too complicated for users. We needed to simplify the installation process , not write lots of help.

Examples of hand drawn mockups for testing user help text. We found these instructions were way too complicated for users. We needed to simplify the installation process , not write lots of help.

Tools for testing complex user help text

If this testing reveals that you need more help text, you'll need to move on to a design tool to add text.

PowerPoint is excellent if you are designing something simple. You don't need it to be a pixel-perfect replica of your intended site. As long as the boxes and buttons are in more or less the right place, it will do the job. To speed up your work, Google for 'powerpoint wireframe template'.

If you have access to a diagramming tool like Visio or Omnigraffle or Gliffy, then you're sorted. These all have wireframe templates available so that you can turn your flowcharting workhorse into a design toolbox.

If you want something more specialised, then there are lots of wireframe tools out there. Many offer free trials or free accounts with limited features. I'm not going to recommend any particular package. The selection changes all the time, and I don't have enough experience with any of them to say which is best.

Once you have a design you're happy with, print it out and test as described above.

What if your users aren't available in real life?

No problem. Use a prototyping tool to take the screen to your user. Marvel and InVision are both excellent, and both offer free starter plans.

Add your designs, and use the animation tools to link buttons and forms. Send the link to your users, so they can test and add feedback to each screen.

You can view an example prototype using Marvel here.

Further reading

GOV.UK Service Manual > Help Text

Some of the links in the post above are “affiliate links.” This means if you click on the link and buy the item, I will receive an affiliate commission. Regardless, I only recommend products or services I use myself and believe will add value to my readers.

Photo by Nigel Tadyanehondo on Unsplash