Making technology more human-friendly, one word at a time.

How to write support documentation

Photo by Kaitlyn Baker on Unsplash

Photo by Kaitlyn Baker on Unsplash

Technical writing can be difficult as hell. Actually, it is difficult. How do you translate technical product knowledge for human beings who might not have the first idea where to start?

My experience at TrekkSoft 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.

Then you also have the problem of working with users whose native tongue isn’t English. While we now translate our support documentation into German, Italian and Spanish, how do we make sure that the right message is passed along?

And finally, how do you make your articles as engaging as possible so that users 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 Support Pages to find the solutions they need without having to reach out to your team for even the smallest of things?

To me, a support article has two functions:

  1. To help them get the job done, whatever it might be.

  2. To let customers know how they can benefit from new features and why they should give it a shot.

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

  • Who is your user base? You can’t write for the company’s profile, but for the individuals within the company who will be implementing your SaaS solution. 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.

  • What are the benefits of this feature? How does it make the user’s life easier/better/faster/simpler?

There’s also additional information you could provide if your solution isn’t industry specific and can be adapted across industries (e.g. Intercom, Monday.com, Trello, Zapier, Square). Ask yourself what are some examples or use cases can you share of this feature being used successfully?

Support documentation for Tip Feature

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? If it does, that is.

  • 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

  • FAQs

  • Troubleshooting common Issues

  • Links to use cases, if any

  • Any additional steps outside of your product (e.g. notifying an account manager)