Providing support for your customers can seem daunting at times. You’re never fully certain if you’re providing the right information, if they understand what you’re trying to say, or whether or not you’re even helping at all. Where do you start? Where do you stop? How detailed do you need to get?

When I worked on refreshing the Support Database, I had a lot of the same questions and concerns. But as I worked on the Database, I found a few things that helped me make it as helpful and understandable as possible, and I want to share those tips with you.

List everything step by step

Putting instructions in a step-by-step format is one of the easiest way to turn a tangled paragraph understandable. You can take something like:

To save a file in the right directory, go to File, Save As, Browse, the folder you want to save in, then change the name of the file and click Okay. You’ve saved your file where you want it to be saved.

And turn it into:

1. Click File
2. Click Save As
3. Click Browse
4. Find the folder you want to save the file into
5. Double-click the folder to open it
6. Change the name of the file if needed
7. Click OK
8. Your file is now saved

If people get distracted, they don’t have to go through the entire paragraph to find their place again – it’s right there, in the step they need.

And not only is it easier for people to understand, it also means you’re less likely to miss vital steps or information.

Use proper names and titles

If you’re asking people to click on a particular button or enter in a particular bit of code, you need to make certain you have it exactly the same as it will appear to them. This not only means you’re checking the process while you’re writing up the details (and catching any problems before you tell everyone what to do), but it also means you’ll be saved responses like “You said to press ‘Enter’, but it said ‘Okay’, so I just left it there and didn’t finish.”

Explain acronyms and abbreviations

At your first acronym or abbreviation, spell it out, then include the short version in parentheses, especially if you’re writing an explanation of it. This gives beginners a guide to what they’re getting into and drives home the fact that you won’t bury the reader in jargon.

Sometimes you won’t need to do this, if you have an assumption of general knowledge within your audience. For example, if you know the person reading the article will be working on their DNS settings, you don’t need to explain what it is to them – they’ll be looking for DNS, not Domain Name System.

Explain new concepts, but don’t reinvent the wheel

If you’re introducing something new into your article, explain it briefly. You wouldn’t expect a small child to pick up addition just by seeing “2 + 2”, so don’t expect the same from your readers.

But, at the same time, you don’t need to retread everything. If that same reader working on their DNS settings has to read through how TCP/IP works just to get to “How to change your name server”, then you’ve gone too far.

Don’t add asides or opinions

When you’re offering help, no one is interested in your opinion. Value judgements don’t have a place in a support article, even ones as seemly innocuous as “This will be easy to do”. If your reader has a difficult time, hearing how easy it’s supposed to be will be even more frustrating. And don’t attempt to upsell by telling them another product is better – this is what they have, and they want help with it.

Use screenshots only if appropriate

Everyone has seen them – the screenshots with personal details badly blacked out (or not blacked out at all), inappropriate desktop backgrounds, strange pop-ups or additional tabs, all the things that instantly distract you from what you’re supposed to be actually looking at.

Screenshots are a great way to show people what they need to do, but they need to be clear, clean, and without distractions. Instead of showing real personal details, set up dummy accounts or information within the panel. Make sure all clutter is removed from the surrounding area. And if you have a bunch of tabs open, take your screenshot in a new window, okay?

Add links only if they’re appropriate

Adding links to a support article can be tricky. On one hand, you can provide your readers with more detail on their problem, a good download, or further documentation on a product. On the other, any links could seem like you’re endorsing that site as a helpful site, and the Internet is always a tenuous and ever-shifting object. One minute, your link to a powerful FTP client seems perfect, the next, you’re pointing them to download malware.

Keep your links focused on manufacturers and suppliers, and keep clear of blog posts and advice sites, if possible.

Make sure you have text as well as video

Instructional videos are great for teaching people how to use systems. Many people prefer seeing how things are used as well as hearing someone talk them through the steps. However, this assumes that the person has the time to sit through a real-time video. Or the ability to listen to the speaker. Or even the technology needed to watch the video.

By adding instructions in text along with the video, you can make sure you have everything covered. It doesn’t need to be a full transcript of the video (although, for accessibility purposes, that would be beneficial), but text that covers the main elements is ideal for people who want to know how to do things, but don’t necessarily have the time.

Have someone test your instructions

Once you’ve written your article, have someone else test the system using your instructions. Have them go through each section, each step, and see if they can replicate the same result. See where they get lost in your instructions. Find out what you can make better.

It’s always better to have someone test long before your customers see the results.

Review regularly

Once you’ve launched the article, make sure you check it regularly to ensure it’s still accurate. Run through the steps to make sure they’re all still there, and that the names have stayed the same, check any links to make certain they’re still working and point to the right locations, and if you have videos, make certain that the pages you are referring to in the video still look the same.

This gives you a chance to consider how well your article is doing, including how useful it has been, what’s missing from it, and how popular it is. By setting up a regular review interval, you can make sure that everything you have up is helpful and not obsolete.

So there are my tips for writing good support articles. What have you learned over the years?