How to write great help articles in your KnowledgeBase

Having a Knowledge Base with great help articles is a must to have for any SaaS product irrespective of their growth stage. I’ve already shared the aftereffect of not having a Knowledge Base for Engagespot and how it affected our onboarding process in this article.

In this article, I will share some tips to write better help articles for your Knowledge Base, and enable your users to find help themselves.

Categorize your help articles properly

Screenshot from a knowledgebase where articles are properly categorized

This is really important. Especially when you have a lot of help articles on your Knowledgebase (which you should), it becomes complex to navigate and find the right article. So, you need to identify the categories, and it’s even better to split categories into several sections.

I’d recommend all SaaS products to have a category that explains common questions about the product itself. Nothing technical, but something like an FAQ where you answer some of the most common questions about your product.

This is important because your users still may not understand if your product is suitable for them even after reading all your landing pages. They will still have questions like – “My app works offline. Can I still use this product?“, “Would I be able to migrate my existing customers to this product?”. Questions like this should be addressed as separate help articles with meaningful titles.

Split dependencies into individual help articles

This is a common problem while writing help guides. Let’s consider we’re writing a help article that explains “How to publish a post with an image on Facebook“. We’re explaining the steps one by one like goto the newsfeed, type the post content and then we need to crop the photo before we can upload it. But can we write the steps to crop the photo in this article? Well, in this case, you may do that, but in a real case scenario, it’s better to write it as a different article.

In programming, they call it “Dependency Injection”. Here, It has two advantages. It keeps the article short and it creates a new article that we can re-use on a different help guide that needs the same explanation.

Don’t Repeat Yourself (DRY) is something that came into my mind (I always relate everything to programming concepts). It is a principle in programming that means you should never write the same lines of code twice. Here, it means never explain the same thing twice. Instead, Write it as a separate article.

Come to the point. Keep introductions short

A help guide is different from a normal blog post. A user who came to read a help article is different from a random visitor who came to your website to read your blog post. A help guide should have very little introduction. And you should address the problem immediately.

Well, we know that introductions are always great because it sets the stage. But it’s totally different for a Knowledgebase article. Because your user knows why he is reading that article. He has a specific problem and he needs to address that quickly. He doesn’t have time to read your introduction.

It’s better to keep intros to just one or two sentences if it all needed. You can quickly explain what are you explaining in that article. This might help the reader to understand if this is the right article for him.

Well, SEO might be a consideration while writing help guides as well. I agree with you. But still, it’s more important to help your customer and make him happy. That should be the primary purpose of your knowledge base articles.

Never write Essays. Write steps instead.

Meme: A cat sitting on top of books bored because TL;DR

Essays are great. But not for help articles. Instead of writing long sentences and paragraphs, try to split the article into simple steps. Highlight the step, and start a separate sub-description if something cannot be explained in a single step.

What I’m trying to say is your primary focus should be on writing as much steps as possible. Everything you write on a help article should be in the form of steps.

Contradicting what I said above, you shouldn’t make assumptions that your users will understand everything that you write. They won’t. When you write a step or a title, it might look obvious to you because you are an expert but your users may not grasp everything they need.

So, have clarity in the steps, and write the steps in detail (even if it seems obvious) so that any user can make use of your help guide.

And, always write the steps in the order in which they appear on your app. For example, start from the first menu item click, and mention every other steps in the exact order. It can be very confusing, if you skip a step.

If something can be different for your user, mention that in the help article

This is one of the frustrating things to deal with while reading help guides and trying to do it ourselves. The help guides explain one thing but what we actually get is totally different – I’m sure you might have experienced this several times.

It’s frustrating because that’s a dead end. We’re stuck!

So, mention all possible worst cases that can happen while performing a step as you’ve explained. For you, it seems obvious and you know what caused that problem and how to fix it. But your would totally feel helpless and most of them won’t have the patience to restart the entire process.

Say for example, if somebody is using Engagespot to send a web push notification and we’ve explained everything perfectly on the help article. But when the user tried, he didn’t receive the notification. Yes, He is stuck. But I know what could have gone wrong because I’m the expert here. The reason simply is that the user has not reloaded his web page for the first time after installing the Engagespot widget. (Which I knew, but the user didn’t)

Since we haven’t explained this in the help guide, the user doesn’t know how to proceed and couldn’t identify what he has done wrong.

So, what I’d suggest is to include a troubleshooting hint wherever necessary in your help article. It could also link to a different article. But mention it properly. For example in this case – Didn’t receive a web push notification? Make sure you’ve reloaded your website after installing the widget.

Then your user can simply go back and retry a missed or incorrectly done step, and find the solution!

Your users would never forget that moment when your article solves exactly what they were looking for.

Last, but the most important – Include as many screenshots and videos as possible

The way in which users consume content has changed a lot. This is the age of video content. Your users have already experienced the convenience of watching videos instead of reading text for pretty much everything.

They expect the same experience on your help articles too. So, wherever necessary, include actual screenshots with proper annotations (I use the screenshot tool on Mac for this).

Video is much more powerful than images, even though it might be a bit difficult to capture and edit your videos. I have used Screencastify to capture my screens and edit them directly from their web dashboard. Or you can simply use the Quicktime screen recorder which is available on your mac.

But make sure to keep your videos really really short and strictly NO intros if you’re embedding inside your help articles.

Leave a Reply

Your email address will not be published. Required fields are marked *