How to write support articles
Photo by Kaitlyn Baker on Unsplash
This article was updated on the 16th November 2019 to include updated ideas and learnings.
I’m a content writer. I began writing for TrekkSoft’s blog, creating top of funnel content to attract leads and drive traffic. Over time, I found myself creating more educational content that tells potential leads and existing customers how they can use our system to make their work lives better. The next thing you know, I’m writing and editing support article. I’m suddenly sucked into the world of technical writing.
And it shouldn’t come as a surprise when I say that technical writing is difficult as hell.
I mean, how do you translate technical product knowledge for human beings who might not have the first idea where to start? My experience at TrekkSoft (a booking system for European tour operators) was eye-opening as we had customers that were both really tech savvy (aka had worked in SaaS companies themselves) and customers who didn’t even know what Google Chrome was (true story).
Then you also have the problem of working with users whose native tongue isn’t English. We translate our support articles into German, Italian and Spanish. How do we make sure that the key message is passed along?
And finally, how do you make your articles as engaging as possible so that readers stick with you till the end and carry out the steps themselves? More importantly, how do you empower your users to find answers in your Help Center or Knowledge Base to find the solutions they need without reaching out to your tech team for the smallest of things?
To me, a support article has one function:
To help users get the job done as efficiently as possible.
So, here are a few questions I’ve outlined that have helped our Product Managers and Customer Success Managers when they had to write up support articles.
Who is your user base? You can’t write for the company’s profile, but for the individuals within the company who will be using your SaaS solution daily. Keep this person in mind when writing.
What is this feature? Tell me in as few words as possible, but make sure it’s clear.
When will your user use this feature? Giving them context can help them understand which part of the workflow it will affect.
How do you use this feature? In as few words as possible, tell the reader how they can use this feature and immediately benefit from it.
When it comes to outlining the actual steps your user needs to take, list out each step by clearly indicating STEP 1, STEP 2 and so on. Most of the time, users will do a quick scan through your article so want to make sure your how-to steps are as clear as possible.
If you need to explain in-depth how to set up a certain part of the feature, make sure to draw attention to it by bolding it or using italics.
Your last step, before publishing should be to edit and proofread the article. Ask yourself if this is easy enough for your user base to understand. If something seems to complicated, get a quick second opinion from someone outside of Product or CSM. (That usually ends up being the marketing team at TrekkSoft.)
Here’s what our typical support doc looks like:
Introduction
What is the topic of discussion here? What feature are you guiding users through? What are you trying to teach your users?
How does this relate to the rest of their workflow?
How can users benefit from this feature?
How to do XYZ
Step 1
Step 2
Step 3
Remember to add screenshots, GIFs or videos to help users understand better.
Additional information (if applicable)
FAQs
Troubleshooting common issues
Links to use cases or blog posts (if any)
Any additional steps outside of your product (e.g. notifying an account manager)
A reminder to edit your support article
After you’ve finished the first draft, read it again to make sure you’ve covered all the important points. Then, edit the living daylights out of your article so that all ambiguity and room for confusion is removed.
Optimising your support article for search
Support platforms like Zendesk, Intercom and HubSpot (new to the game) provide a search bar for users to type in terms or questions in hopes of finding that specific insight to solve that one tiny problem that’s really not worth opening a ticket for.
Your role as a technical writer or the person editing / reviewing the support article is to also optimise the article for search. What would a user search for when trying to complete this task you’re writing about? Remember to include key terms and phrases to make it easy for users to find it.