You've got a great SaaS product but how do you keep your knowledge base accurate when you update it? In this guide we'll go through some strategies you can use as a customer support person, engineer, and product manager.
Download PDFYouâve got a great SaaS product. Youâre shipping fantastic updates and you feel youâre on course for an amazing future as a company.
But youâve gone one problemâyour customer support is crumbling. Youâre inundated with tickets and new features arenât getting the adoption your team would like. All while fielding new customer requests.
Youâve got a knowledge base so why isnât it working? Isnât it meant to help reduce ticket volume? It might be because itâs not accurate. Itâs not in sync with your product and itâs lagging behind. Every time you launch a new feature thereâs the potential of making information on your knowledge base inaccurate. Major updates are bigger hits to the accuracy but minor updates are just as dangerous.
â
With a product-driven company you need to be able to explain these exciting new features to existing and new customers. Trouble comes when youâre shipping a lot but not updating your knowledge base along with it. Even small bits of outdated information matter.
Itâs understandable. A knowledge base isnât usually a priority and it can become a pain to update. Consumers like chatbots due to instant responses. But when it comes to answering questions in large batches with a lot of detailed information nothing else comes close.
You obviously want your customers to have a great experience which is why youâre reading this guide. As fantastic as your support could be itâs still much easier and less time consuming if a user can depend on a self-service knowledge base.
In this guide youâll read some tips on how, when, and where you can keep a knowledge base top of mind. There's strategies and templates for customer support teams, engineering teams, and product managers.
Youâll also learn about some real-world examples from some awesome people at Front, Buffer, and Zapier. But first letâs take a look at the problem your team and your customers are facing in a bit more depth.
From my experience as a user it can feel like a pointless task searching for something on a knowledge base. It hardly ever works. Itâs like a game. Will it find an article for my search? Unlikely. But like 82% of customers I think itâs quicker than getting in touch so Iâd better give it a go.
Then it happens for the first time in forever. You actually find what youâre looking for. Magic. This is what 91% of consumers wantâa knowledge base tailored to their needs.
This is what you want your users to feel. Like they can search for something and find an answer without wasting their (and your) time asking something that shouldâve popped up.
The trouble is getting this to work is hard work. Like, really hard work.
If youâre in customer support youâve experienced this. Your product team ship one new feature that doesnât have any articles and a flood of tickets roll in. Customers want to know what it does and you donât have the information you need to answer them.
You want to crawl into a shell like a snail and blame engineering.
But itâs no better if youâre an engineer. Youâve spent weeks on this awesome new feature with thousands of lines of code and it gets no user adoption. Youâre getting feedback that itâs not super clear how it works or what it does.
âThatâs not my jobâ you cry. You also want to hide in a shell and blame customer support.
And if youâre a product manager youâd better hide in your shell for a while. As the person who helped plan out the feature and ship it, itâs your responsibility to have both engineering and customer support on the same page.
If nobody is using the new feature, it has been a huge waste of resources. Bye bye bonus.
Unfortunately for you I donât have the answers. There isnât a magic formula to make this better. But I do know itâs all about building a knowledge base into your product building culture and making sure support, product, and engineering are all helping out.
Having a knowledge base thatâs accurate and helps customers use your best value features? That can keep revenue up, team tensions mellow, and in the end customers happy.
At HelpDocs we ship a lot of code. As founders weâre both technical and both work on product every day. But weâre also involved in customer support. And as a knowledge base company we focus on keeping our knowledge base fresh and updated.
Letâs take a look at common elements in a knowledge base youâll want to look out for when keeping your knowledge base up to date.
When youâre updating knowledge base articles a lot you tend to find certain patterns. There are some elements that are usually the first to become outdated because of their high production like video. Others are more easily fixed but forgotten in a sea of words like dead and buried features that didnât quite pan out.
Below are some common themes and elements inside knowledge base articles that tend to fall behind the product. Each has a commonality rating based on how often it happens and an influence rating based on how important it is to update.
â
Commonality: Very common
Influence: High
Screenshots can be super helpful when demonstrating where to click or what the page youâre trying to find should look like.
The issue with adding screenshots is that when your product changes you have to go back and update them. So while very useful for customers itâs a pretty big pain for people working on the knowledge base.
Commonality: Common
Influence: High
Videos are a lot easier to digest for visual learners but they can be time-consuming to produce. This means that when you do produce one and the product changes it can be tough to step up and redo the video.
Commonality: Very common
Influence: Average
Your product team are probably pumping out product updates. That means your navigation will likely change quite a bit over the span of a yearâit has to fit somewhere!Â
Settings pages are usually the first to be targeted so keep an eye on them.
Commonality: Uncommon
Influence: Very high
As your SaaS product gets better and improvements are pushed itâs not uncommon for pricing to change. This is especially true for early-stage products. You might even decide that youâre targeting a different kind of customer.
Make sure youâre referencing the right plan names and features in the right places.
Commonality: Uncommon
Influence: Low
Most teams are pretty amped up about new features so while this is a common thing to write about itâs pretty uncommon that these new features donât get new knowledge base articles.
Make sure you know how customers use this new feature and you include knowledge base articles as part of your release plan.
Commonality: Common
Influence: High
Sometimes a feature just doesnât work out. It either doesnât have any interest from customers, costs too much to run, or both. Make sure you donât introduce new customers to phased out features.
Commonality: Very common
Influence: Very high
If you ask anyone whoâs worked on a knowledge base youâll find that theyâve probably found themselves updating or redirecting dead links. A dead link is a link that leads to an expired URL. Either the knowledge base article has been moved somewhere else or has been renamed.
Itâs difficult to track these down and they require a lot of effort to keep updated but theyâre vitally important to correct.
As a support person itâs tough to take a step back sometimes. Youâre probably answering a lot of tickets every day or managing a team that does. Your answers have to be accurate, reliable, and friendly.
And honestly itâs sometimes difficult to be friendly on a daily basis.
So while youâre dealing with a variety of different tickets a knowledge base is undoubtedly not on your mind. And no matter the title every support person has a core responsibilityâto serve customers. Providing them information, passing on product feedback, and advocating for their needs and wants.
What isnât always clear is whether the information youâre passing on is accurate. Pockets of information like canned responses, internal notes, and public facing knowledge base articles naturally become outdated.
If we notice before the partner does and it's a quick fix, anyone on our support team will do it on the fly. We make documenting stuff super fast, so it's fast for someone to make changes as they work. We have a 'Default to Action' policy here. So if something needs doing and you can do it - we just do it and get it done.
Lindsay Smith
Customer Support Manager at Zapier
Why is it natural for things like these to go stale? Because they require an awful lot of collaboration, attention to detail, and effort.Â
It feels like non-essential work to look through and audit these things but providing outdated information is like a crack in a dam. If itâs not repaired quickly the rest of the dam breaks leading to a gush of waterâor in this case tickets and confusion.
So what can you as a support person do to stop this build up of bad information from happening? Letâs take a look.
Itâs very rare new features get shipped without a lot of prior planning.Â
Loads of companies use a product roadmap to keep the whole company on the same page. Itâs kinda trendy these days. But they all have the same basic columns: suggestions, next, in progress, and shipped.
What you want to keep an eye on is the next column. If thereâs a due date itâs a great opportunity to take note of any knowledge base articles that may get affected by the change.
Thatâs exactly why we built a due date into our Stale feature. Being ahead of the product updates mean you donât find out later that thousands of customers have been fed the wrong information and you donât have to go digging around.
There are of course other ways to get around this problem. You could:
No doubt your company will have meetings where your product team discuss whatâs next to be built, how to build it, and what pain points itâll address.
Attend these product meetings to get the lowdown on new features or updates to existing ones. Besides, you speak to the customers the most, so youâll have experience knowing what they care about.
Working at a high growth startup has its challenges. Since Front is constantly changing and getting new features, our documentation, how-to tutorials, and product images can quickly become outdated. I stay in sync with our product team on new features through weekly meetings and keeping a running list of knowledge base articles to update, the required changes, and when they're due.
Cori Morris
Customer Support Manager at Front
Make short notes about affected features and how they might be changed. It might be useful to jot down a few keywords so you can quickly search for them later if your knowledge base is on the larger side.
If you want to get more in-depth after your meeting is over, we have a template you can use. It has more columns so you can include much more detail.
If you really want to know whatâs going to be shipped before itâs shipped head over to where your engineers are.
At HelpDocs we use Github to push, review, and merge new updates to our product. Itâs the place every single code update goes through. Thereâs going to be a piece of software your company uses for pushing code too. It could be GitLab, Bitbucket, or something else.
This is the place you could get ahead of any product updates, especially major ones. Thereâs usually a way to set up modular permissions so you can be invited with access to comment and get notifications, but without the ability to push code yourself.
If you head to Pull Requests, youâll find out whatâs ready to be reviewed or is currently in review. The size of the commit (how many lines of code were deleted or added) gives a good indication of how big the change will be for customers.
For us anything over 1,500 lines of code changed is a substantial update, meaning something has probably changed for the customer. The size of a âmajor updateâ depends on your team and how many lines changed is normal, small, or large.
Once everything has been reviewed for the engineer(s) youâll find that thereâs an indication that it has been merged.
For smaller teams like us this means itâll go through a few more tests before going live. For larger teams there will be some quality assurance so youâll have some time before the feature goes out into the wild.
Once tests are in progress this can be a good opportunity for you to understand the feature. How does it affect the customers? Does anything need to be updated in the knowledge base? Remember to be proactive when commenting.
Just thought Iâd jump in here. Looks like this update might affect the way [feature] works. Will these docs need to be updated?
[LIST OF DOCS]
Engineers will have deep knowledge of the changes so should be able to help you out pretty quickly.
Running a knowledge base audit can be time-consuming but itâs the only way to ensure accurate, quality information is given to your customers. Since a knowledge base can save thousands of tickets, itâs worth the effort.
Itâs unlikely youâll want to do this monthly let alone annually since itâs such a demanding and frankly laborious task (I guess Iâm not selling the idea here, am I?). It is worth the effort though since youâre potential saving a ton of tickets from getting to the support channels.
As there are so many integrations, we try to carry out audits for the top-performing apps as part of our strategy to ensure these are up to date. As well as working closely with our Partnership and Engineering team when new or existing apps integration need a more bespoke approach to their help docs, than the normal templates we have. In addition, reactively work through customer feedback as much as possible.
Jessica Valero-Gil
Technical Writer at Zapier
â
So how do you run an audit? Itâs pretty simple.
First off youâll want to download a list of your articles. You should be able to find a way to export your articles inside your knowledge base software. If youâre using HelpDocs you can find out how to do that here.
In this example weâre going to reference our CSV export file since itâs the most common type of export to find.
Next youâll want to use your product roadmap as a tool. Build a list of keywords that may be mentioned in an article. Thereâs no point in trying to look through every article body to start with.
For example we released a new template customers can use called Bars V4 earlier this year. Hereâs a list of keywords Iâd want use to find the articles that needed to change:
To scan for relevant keywords you can use the built in search tool. As you can see below I got 48 results for the term âthemeâ. It was far easier to do that than scan through every article.
Then comes the labour intensive partâlook through each article body to check everything is up to date and makes sense. Hopefully youâll stumble upon the same articles for multiple keywords. Good luck!
No matter how on top of your knowledge base you become chances are your customers will find some misinformation in your docs. If this happens youâll want to be proactive to make sure the article gets updated.
For moments like these itâs great to have one place where you can record which article is outdated, what the customer found confusing, and how urgent it is. You could record this in a spreadsheet or in kanban software like Trello or Clubhouse.
We use Trello to add new cards any time a new feature is added and needs an FAQ, or if an existing FAQ needs to be edited. We also encourage our Customer Advocates to create new cards if something is missing from the FAQ or isn't clear.
Kelly Vass
Customer Advocate at Buffer
At HelpDocs we have an Escalations project set up in Todoist where we put any customer tasks or bug reports. When a customer finds misinformation we tend to add it to this board, mark it as Stale in HelpDocs, or update the article right away.
If youâre a SaaS company chances are youâre using a tool like Slack, Twist, or Discourse for your team communication. Iâd also hazard a guess that a lot of decisions about product are made there or at least discussed there.
This a fantastic opportunity for you to notice feature discussions and pull requests coming in.
Keep an eye out on #engineering and #product channels to make sure youâre in the know about whatâs about to be shipped and how it affects your knowledge base.
Building software is hard. It takes years to get used to writing code, test it, review it, and worst of allâdebug it. The last thing on your mind as a software engineer is making sure the knowledge base is up to date. Thatâs the support teamâs job, right?
Well, yes. But also no. Sure the knowledge base comes under the jurisdiction of the support team but if youâre the one pushing the changes you know whatâs changed. You also know why it has changed. Youâre in a great position to help the support team out.
Keeping a knowledge base accurate and reliable helps everyone on the team.Â
The support team get less tickets coming in and as an engineer, you get less duplicate issue reports that arenât actually issues. With an up to date knowledge base itâs more likely your product updates will get used correctly too.
Here are some easy ways you can help your support team out with keeping your knowledge base relevant.
Youâve pushed thousands of lines of code to hundreds of branches, merged into develop, and pushed to production. Have you ever thought about how those changes affect your knowledge base? Probably not.
Yet youâre the one most equipped to share how these changes affect your product. Getting into the habit of giving customer support a rundown of changes can make a huge difference.
There are some places in the development pipeline that you can use to share how these changes affect the product.
In addition to explaining what code youâve added and why, explain how it affects existing features and how this might change behaviour for the customer. Hereâs an example from one of our own pull requests.
This is helpful for the support team because it explains:
Here are a few quick templates you could use to help you fill out your pull requests to become more helpful and proactive:
Improved
New feature
â
But writing it out isnât the only thing you can do.
One simple way to make it a lot easier is to record a GIF or video. For small changes we use Licecap to record some quick GIFs.
For larger features we record a Loom video and go through the new process. This helps your customer support team understand how the feature works, how the customer should or shouldnât use it, and gives everyone a digestible way to understand your awesome new work.
If youâre about to launch a new product feature and youâre in a large team, chances are youâre involved in a few meetings about launching the feature.
In these meetings itâs a good opportunity to point out how itâll affect the knowledge base. Help the customer support team understand how the feature is used, who uses it, and what needs to be written down for customers.
You can do this with a feature brief. Explain:
So youâve merged in some code into production. It might be a teeny bug fix which makes the feature work as intended.
If it does affect the platform itâs a good opportunity to contribute some knowledge yourself on the knowledge base. As an engineer, you shouldnât be worried about getting in the way since keeping a knowledge base updated is a team sport. It takes a lot of attention and accuracy.
Product managers have a tough job to do. Having to push the product in the right direction while keeping engineers motivated and support people updated on progress. This usually amounts to meetings, meetings, oh and more meetings.
But these meetings can be more useful. And your feature can receive better adoption. And you can keep your teams in sync more easily. How? No surprises hereâby keeping your knowledge base top of mind.
Ok I can feel your eyes rolling from here. But I canât stress this enough (well I probably can but thereâs no stopping me). Your knowledge base is the foundation for your customers, your support team, and your product.
A good one can make one hell of a difference. So letâs dive into how to incorporate it into your daily duties.
Iâm guessing you have meetings with a customer support manager. And also an engineering manager? If not it might be a good idea.
By having product and support in the same meeting with you, engineering can explain the progress they made for the new feature and how it works while support can write notes to prepare the rest of their team in assisting customers and educating them.
But this just doesnât have to happen in meeting rooms. Using your roadmap you can comment and tag other team members to keep everyone on the same page. Paste in meeting notes and summaries.
Detail any features it affects so someone can take a look to see if any knowledge base articles will need to be updated.
Features only get shipped because they solve a problem for customers. Take our Smart 404 page for example. The issue was customers running into outdated links or no active link at all.
After some thought we decided we could take the keyword theyâre looking for from the URL, search for it on the knowledge base, and suggest some articles that might interest them.
By writing down what it solves it was far easier to get an article published. Just take a look at the intro of the article:
Let's face it, nobody wants their customers to visit a 404 page. If it happens, something has usually gone missing or they've been directed to the wrong place.
That's why we've created Smart 404s, a way to automatically direct your lost customers to the article they were looking for.
This gives the customer (or lead) and lowdown on what the feature does for them. It directs their lost customer to a useful relevant place in their knowledge base.
Writing this down also helps you understand where it fits in your knowledge base (aka the taxonomy). Does it require its own category? Does it fit in an existing category? This should help answer these questions.
So your awesome feature is going to be shipped in less than a week. While youâre likely terrified and succumb with stress now is a great time to call and meeting with the entire support team.
Since you know how the feature will work you can helpful and proactive by:
If youâre offering a beta for a new feature you can use this opportunity to see whether the idea for a new category or if the new articles make sense in context.Â
Get relevant feedback from your testers with information about:
Whether youâre part of the support team, an engineer, or product manager, all hands need to be on deck to keep your knowledge base fresh, relevant, and useful. Hopefully this guide gave you some strategies to try out and integrate a knowledge base into your processes.
We power millions of article views every month and help keep teams organized with their documentation. You can learn more about the HelpDocs platform over here.Â
If you have any other questions feel free to reach out!
Previously the search input on all templates would be focused on when the page was loaded regardless of whether they were on a mobile device or not. This led to visitors having their mobile keyboards pop up right away which wasn't ideal.
This checks a visitor's screen size and only focuses on it if it is more than
800pxwide.We could've checked the user agent but from what Iâve read this is unreliable.