It’s not uncommon to visit a website and be impressed by what’s there. Encouraged, you buy from them.

It’s only when you need some assistance with your new purchase that you realise the online help is woefully inaccurate. Lacking in depth and quality, it feels like a last minute bolt on. And all-too-often, it is.

Whether you’re a professional writer or not, if you get given the job of producing online help articles, please think about your approach before you get stuck in. It can be hard to hit the spot, and as a reader, there’s little more frustrating than being stuck with a problem you can’t fix.

I spent much of the first half of this year writing help articles and tutorials. I reckon I got a reasonable feel for what works, and what doesn’t. So here are some tips to make help articles clear and understandable:

1. Use numbered lists, not bullets. When people follow your instructions, they’ll often be flicking between their web browser and other windows. It’s easy for people to remember that they were on step five, so put instructions in numbered lists.
2. Break complex processes right down. It’s better to have a longer list of simple steps than a short list of complex ones. A good rule of thumb is that people should be able to read each step, then follow it without having to refer back to the instructions half way through.
3. Use screenshots to complement written instructions, not to replace them. Screenshots are a really good way of showing people what to do. But not everyone will be able to see them – think about people using screenreaders or on slow connections. By all means, use images to make it blindingly obvious which button to click. But make sure your copy spells everything out too.
4. Underestimate the IT level of your readers. If your audience is a tech-savvy bunch then you won’t have to explain every single point. But if you’re not sure exactly how much they know, or the audience spans a range of levels, err on the side of caution and explain things more fully. A few of your most knowledgeable readers might feel a bit patronised, but everyone will understand everything properly.
5. Think about the permutations. Are your instructions valid for Windows XP and Vista? What about Apple Macs? Have you thought about different web browsers? And don’t forget about the user’s preferences – make sure your instructions match what’s on their screen. Try and take care of the most common permutations at least – if you can, use web metrics to find out what software your audience typically uses, rather than relying on guesswork.
6. Do some testing. The instructions might be blindly obvious to you, but that doesn’t mean everyone else will be able to understand them. Ideally, get some typical readers to follow your instructions. At the very least, get a friend to look them over.
7. Be consistent and be precise. Use the correct terminology, and use it consistently. Don’t tell people to ‘press’ a button when actually they should ‘click’ it. And if there’s any ambiguity, explain things so they’re clear. I had to write online help content for a popular piece of security software – some screens had two ‘Configure’ buttons on. It was a hassle explaining which one to click every time, but it had to be done.
8. Don’t reinvent the wheel. If the articles you’re writing deal with problems with someone else’s software, link off to their help pages rather than duplicating it on your website. After all, they made the software and so they’re in the best position to document it.
9. Get to the point and don’t joke around. If I’m having a problem with your product, I want it fixed. I don’t want to see clever puns or over-elaborate copy. Get to the root of the problem, and get it solved. Quickly.
10. Don’t try and sell other stuff. If someone’s having an issue with your product, it’s not the time to persuade them to buy something new from you. Just fix the problem efficiently – that’s a good way to keep your customers loyal.

Any more suggestions? Leave a comment and let me know.