Ship & Sync: Keeping Your Knowledge Base Updated Alongside Your SaaS Product
  • Go back to guides

Ship & Sync: Keeping Your Knowledge Base Updated Alongside Your SaaS Product

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.

Introduction

You’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.

As you ship more features your knowledge base gets more outdated


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.

Search, Ship, Blame

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.

The experience you want users to have vs. the experience they actually have


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.

Outdated Elements You’ll Want to Look Out For

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.

Issue Commonality Influence
Navigation changes Very common Average
Pricing & plan changes Uncommon High
New features missing Uncommon Low
Old features phased out Common High
Dead links Very common High


Outdated screenshots

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.

Outdated videos

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.

Navigation changes

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.

Pricing & plan changes

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.

New features missing

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.

Old features that have been phased out

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.

Dead links

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.

Keeping a Knowledge Base Accurate as a Support Person

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.

Lindsay Smith

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.

Keep an Eye on Your Product Roadmap

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:

  • Add links to relevant knowledge base articles in the product update information card or task
  • Make a calendar event for when the feature might be shipped
  • Add a note in the article explaining that things might change in the near future
  • Create a spreadsheet that includes a link to the knowledge base article and when it’s due to go out of date

Attend Product Meetings

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.

Cori Morris

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.

Go Where the Engineers Are

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.

Pull request: lines altered

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.

Pull request: comment

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.

Run a Knowledge Base Audit Yearly

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

Jessica Valero-Gil

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:

  • Template
  • Theme
  • Version
  • Brand

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!

Be proactive when customers find misinformation

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.

Kelly Vass

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.

Keep an eye on product chatter

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.

Keeping a Knowledge Base Accurate as a Software Engineer

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.

Build it into the development pipeline

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.

Pull requests

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.


🚀super-engineer commented 10 days ago

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 800px wide.

We could've checked the user agent but from what I’ve read this is unreliable.


This is helpful for the support team because it explains:

  • How it worked previously and the issue we came across
  • What we did to improve it
  • How it behaves now

Here are a few quick templates you could use to help you fill out your pull requests to become more helpful and proactive:

Improved

🍄mushroom-luva commented 16 days ago

[Technical detail]

Previously we [did this]. This was an issue [because].

This [is how it works now].


New feature

🐲dancing-dragon commented 16 days ago

[Technical detail]

This feature does [did this]. We built it [because].

This [is how it works].

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.

Pre-launch feature briefs

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:

  • What the feature does
  • If it affects existing features or workflows (and if so, how)
  • What the main problems it solves are


Become proactive when shipping features

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.

Keeping a Knowledge Base Accurate as a Product Manager

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.

Keep customer support and engineers in sync

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.

Write down the main pain it solves before shipping

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.


Our Smart 404 Pages

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.

Prepare the support team

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:

  • Demoing the feature. Show how a user would use the product from default load to finishing
  • Pre-empt possible questions. Sometimes features are complicated or they’re harder to explain. Prepare your support team by writing a list of possible questions along with some answers to make it easier.
  • Suggesting relevant tags. In most knowledge base software you can add tags to make the search more relevant for keywords. Use this time with the support team to come up with these.

Beta feature? Write beta knowledge base articles

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:

  • If the article made sense
  • How difficult it was to understand the concept of the article
  • If any other media formats would’ve helped their understanding

Wrapping Up

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!