Ten tips for writing support articles - Heart Internet Blog - Focusing on all aspects of the web

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.

Screenshot of a step-by-step guide from the Heart Internet Support Database

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.”

Screenshot of a step-by-step guide using the proper names of steps from the Heart Internet Support Database

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.

Screenshot of a guide that explains what the acroynm FQDN means in the Heart Internet Support Database

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.

Screenshot of a guide explaining Linux in the Heart Internet Support Database

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.

Screenshot of a guide explaining how to upgrade a server in the Heart Internet Support Database

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?

Screenshot of a guide with a screenshot in the Heart Internet Support Database

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.

Screenshot of a guide with a link to PuTTY in the Heart Internet Support Database

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.

Screenshot of a guide with a video embedded in the Heart Internet Support Database

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.

Screenshot of a step-by-step guide in the Heart Internet Support Database

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.

Screenshot of a guide in the Heart Internet Support Database

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

Subscribe to our monthly Heart Internet newsletter, filled with the latest articles about web design, development, building your business, and exclusive offers.

Subscribe now!


Please remember that all comments are moderated and any links you paste in your comment will remain as plain text. If your comment looks like spam it will be deleted. We're looking forward to answering your questions and hearing your comments and opinions!

Leave a reply

Comments are closed.

Drop us a line 0330 660 0255 or email sales@heartinternet.uk