How to Build an Effective Support Knowledge Base: Everything You Need to Know about Documentation

By Jess Byrne - Published December 3, 2015 -

You are reading: Chapter 9 of 12

It's 11p.m., you're driving down a remote road on a clear, starry night when Pop! the stillness of the dark is shattered by a blown-out tire. You're safe but stranded in the middle of nowhere.

Denial and panic are soon followed by acceptance as you realize there must be a spare tire and jack somewhere in the car. And so, almost without thinking, you open the glove compartment and reach for your car manual.

You never took time to read it before—you have better things to do than read a manual. But now that you need it, the manual is your best friend. You owe your sanity to the writer and designer who made your first time changing a tire seem like a familiar chore.

Documentation is important. It's the hidden work behind the flashy products, the humble text and graphics that give you knowledge on the fly when you need it most—without requiring someone to personally assist you.

It's easy to ignore documentation, and offer your product to customers without a user guide, help menu, or tutorial. But if you want to set your team and users up for success, everything needs documentation.

How to Set Up a Help Center

  1. Decide What to Document
  2. Structure What You Document
  3. Host Your Documentation
  4. Organize Your Help Center
  5. Surface Your Documentation
  6. Keep Improving Your Documentation

Why Documentation is Important

Documentation everywhere
Documentation is all around us

The Help menu in Google Chrome? That's documentation. The owners manual that came with your car? That's documentation. IKEA's sometimes hilarious drawings that came with your BLÅVIK bookshelves or BJÖRKUDDEN table? Yup, that's documentation too.

Documentation is the media—text, images, and video—that explain a product or service, the "material that provides official information" according to the Oxford dictionary. Whether it's a leaflet that tells you how to use your public transit pass, a guide to an internal standard operating procedure, or the knowledge base in Microsoft Office's Help menu, documentation delivers everything from the basic to the advanced.

"The goal of documentation is to turn novices into experts," says programmer and blogger Steve Losh. "Think of your documentation as a lesson (or series of lessons), because that's what it is."

"The goal of documentation is to turn novices into experts."- Steve Losh, programmer

If you have something that describes how your product or service works, that's documentation. It's something every business and product should have.

But no one ever reads documentation, you say. I never do. That is, until your tire pops.

"The reason why it doesn't seem that [people read documentation] is because those are the ones that never call you," says Joe Cieplinski, a developer at Bombing Brain Interactive. "They read it and they got their answer and you never hear from them."

People do read documentation. They might not read every last page of a manual, but they will search online for help or click through tutorials to learn how to use a product. Research firm Gartner has found that most people would rather find help documentation online and fix their own problem than call a support center. They'll look for documentation, and expect you to offer it when they need it.

Here are the best reasons to take the time to make great documentation for your products.

Help Customers Help Themselves

It's not selfish to want to reduce your support workload—most people want to be able to solve their own problems. As Cieplinski says, "I know from personal experience last thing I want to do is contact developer and ask them a question." That's why his team offers as much documentation with their products as possible.

As a user, it's frustrating to not be able to figure something out. Some people immediately call or email support when they hit a roadblock, but plenty more want to fix their own problems and learn more on their own. Documentation gives customers the chance to shine on their own. They'll fix their own problems, feel empowered, and hopefully love your product for it.

They'll also be far less likely to need personalized support from your team—or at least they'll understand the product and problem better, making the final support ticket easier to solve. You can even reference your documentation when answering support tickets—another trick Bombing Brain uses to teach customers. "We'll write, 'Here is the answer to your question about this feature and this is how you do it and by the way, this is all on page 47 of our manual,'" says Cieplinski.

If customers look for documentation and can't find it, though, that'll only make your product look worse. Most people expect products to come with at least some documentation—this is a chance for your team to stand out with even better documentation than users expect.

Support Your Own Team

You can use a product for years, and still manage to not know everything about it. It wouldn't be surprising at all to find a Toyota designer who doesn't know how to change a tire on a Prius, or an Apple developer who doesn't know how to add a new language to the keyboard.

That's why Freshdesk says that "a knowledge base is the one thing that can be instantly useful for both your support agents and customers equally." Your internal team needs to know how to use your product, too, whether for their own reference or to help customers with problems.

Document everything, and your team will be able to quickly find how to do anything in your product. Neglect it, and your support team will waste hours each day searching for solutions that should have been documented from the start.

There's another advantage for your team: consistency. As information architect Vinish Garg says, "When [everyone is] referring to the same content via a knowledgebase, it ensures consistency in what all customers learn from the support team."

Document your product once, and then you'll always know exactly what to say each time a customer asks a question.

Build Better Products

It'd be easy to design a tire that takes 2.5 hours to change without anyone on the design team noticing. Document the process, though, and that problem will quickly come to light.

That's why data scientist Nimit Kalra suggests you write documentation before you build your product. "Writing your documentation beforehand allows you to spot and suppress any bugs or issues that may arise during the actual development," he says.

Even if you write your documentation after the product is built, you'll notice pain points and problems in your product. Perhaps they'll just require better documentation, but more likely, they'll inspire you to go back to the workbench and make your product better before shipping it to customers. As entrepreneur Sam Carpenter says in his book Work the System, "documenting a seemingly flawless system will often reveal small imperfections."

7 Steps to Setting Up a Help Center

1. Decide What to Document

Gumroad Creatorpedia
Don't let Gumroad's 4,000-word documentation article intimidate you.

Now, it's time to write. To shoot videos. To diagram your processes and describe everything you've made in a way everyone will understand. It's time to work.

Creating documentation is important, hard work, Carpenter says. "This is not a feel-good exercise. It's the mandatory foundation for creating tremendous efficiency. This is the one-time heavy lifting."

Effective documentation can not only help inform your customers about how your product or service operates, but help keep current employees up to speed—and can even surface defects in a system or process. It's critical work that's worth taking the time to get right. It's a "mandatory foundation for creating tremendous efficiency," Carpenter says.

With that much at stake, creating documentation can feel daunting. Where do you start?

"Just start," says Chris Gallo, a member of the Highrise CRM support team. "Break it apart into smaller pieces. Try writing one article today. That's it. Before you know it, you'll build momentum."

Start by documenting the most obvious things. Walk through your product or service, and write about each part of it. Keep a list of the things you think need documented—often surfaced by customer support tickets—then cover them one at a time. Understand user pain points by walking through the process yourself and answering questions or concerns you think users would have.

Don't stress about how to write, or what to write. For now, just document all the things.

2. Structure What You Document

Smartsheet help documentation
Smartsheet offers a help article on creating a new spreadsheet before one that discusses inserting columns.

Documentation is only effective when structured correctly. Forget to tell a car owner to jack their car before removing the lug nuts, and you'll have an angry customer at best and a lawsuit at worst. And if you don't include a diagram, few would recognize the jack at first glance, anyhow.

Explain Everything

No matter what you're documenting, your documentation needs to be just as clear. Fog Creek Software founder Joel Spolsky says useful documentation should be "enough to teach people who are new to the domain what the product is trying to do." Teach people everything there is to know about both your product and the industry it's for—which is why, in an example he offers, QuickBooks explains both accounting concepts and how to use their software.

"Write as if the customer is a beginning user of your product," says Gregory Ciotti of the Help Scout team. "Skip the advanced terminologies and jargon." Don't assume customers know what you're talking about; use plain language. It's okay to over-communicate.

Get your whole team to join in—don't go at it on your own, and don't worry if you don't understand everything. "Your team needs to have a say in [documentation], and be able to pitch in," says Highrise's Gallo. "Their perspective is invaluable." Get developers to explain technical terms, designers to break down workflows and menus. The more people on your team that help with documentation, the more you'll teach your customers.

Teach in Logical Steps

And you need to teach. "If you want to write better documentation, you need to practice teaching," says Losh. "You need to practice the art of rewiring someone's neurons with your words." You don't need to teach people every possible thing—or as Losh says, "you don't need to give someone a degree"—but you do need to teach them enough to to be successful with your product.

Teach the ABCs first, then how to make words, then how to make sentences. Put things in orderly steps. Jack the car up, then take the lug nuts off, then pull off the old tire.

Multimedia is Good

Smartsheet provides a video tutorial as part of its documentation on creating a spreadsheet.

It's good to use more than just text in your documentation—scratch that—never rely on just text for documentation. Experiment with video walkthroughs for complex features, GIFs to explain simpler concepts, and pictures or diagrams to show what you're saying.

Cater to different types of learners. Images are super helpful for visual learners when explaining a concept, while a step-by-step tutorial may be better for more analytical learners. Use apps like Skitch or Preview to mark up and add instructions to screenshots—something we do often at Zapier in order to better illustrate a process.

Watch Your Words

Media isn't the only important aspect of a well-structured article. As a team, you'll want to come up with language and tone guidelines you want to use with customers, like those MailChimp or Buffer made for their team. Then, make sure that tone and language is consistent everywhere.

Pick the terms you'll use for technical features, and figure out the simplest ways to describe everything. Choose one style of writing—a personality, perhaps—and stick to that. A complicated professional tool might need more scientific wording; a just-for-fun app's documentation could use a bit of humor.

Format Matters, Too

It takes more than text and diagrams to make great documentation. Formatting articles well for easy browsing is equally essential. Sure, people could search through your documentation for a specific tip, but you'd do much better to make everything easy for customers to find.

Freshdesk recommends you treat each article like a mini onboarding process and always state prerequisites. Use simple titles, bold text, and big headers to make it easy to scroll to exactly what you're looking for. Add bullet points and tables to quickly explain simple steps and points. Tag articles to display related articles and to interlink articles together.

Make Everything Reusable

Explaining every feature a dozen times is no fun. So don't do it. Explain each feature, then link to that explanation any time the feature comes up. Then if you ever change that feature, you only have to update that one documentation article.

Also make your content easy to move around. We write in Markdown at Zapier, using asterisks for italics and brackets for links. Markdown makes it easy to write in plain text and then turn it into rich text or HTML when needed. You could write in HTML, but it's difficult to read through on its own—and rich text is unreliable, so you won't be certain it'll look the same in your help center as it does on your computer.

Dig Deeper

Much of the best documentation comes from looking at what your support tickets are telling you. Look at the questions you get asked the most often—something you can often find by seeing how many emails have a specific tag, or by noting how often you reply about different topics. Find which tickets get replies back needing more info and which are solved on the first response.

Those topics are the best things to cover—the things your customers are telling you they need help with.

The more time and effort you put into making a great article can significantly cut down ticket volume. You're already taking the time to write documentation and shoot videos—take the extra time to edit the copy, ensure the tutorials are structured correctly, and make sure your documentation is accurate and thorough. That time will pay off in spades.

3. Host Your Documentation

Slack help documentation
Slack relies on Zendesk to host its help center.

When your car has a flat tire, you instinctively reach for the glove compartment. That's where almost every car's owner's manual lives, and there's no reason to assume this car would be different.

Even in today's Google-first world, it's still second-nature to check back in your TV's box for the owner's manual, or to mouse over the Help menu in a program when you get stuck. So put your documentation where people expect—that may be in your website, behind a Help menu, or underneath your widget.

As a rule of thumb, most products today should have online documentation, something that's called a "support center", "knowledge base", or "help center" depending on who you ask. Even if you have printed paper documentation or a Help menu in your software, the online documentation lets users find solutions to their problem from your website or via Google.

It's only natural to Google for solutions, and also second-nature to look for a support page on a company's website, so make sure people find your documentation when they look. You can find ours at, but it's also common to use,,,, or

There are dozens of tools to help you build a knowledge base on your site—you'll find a documentation tool in most of the best customer support apps, where you can write in rich-text, HTML, or Markdown and easily publish your documentation online. Or, you could host your own documentation, using a WordPress blog or even a plain website. We made a customized Django app for our documentation at Zapier; the Highrise team is using the plain-text CMS Jekyll.

But don't stop there. If you're documenting a Tesla, print out your documentation and turn it into a paperback book. Put your documentation anywhere your user would expect to find it—your online knowledge base isn't enough on its own. Bombing Brain Interactive, the Omni Group, Pixelmator and other iOS developers put their documentation in the iBooks Store as an eBook so users can download it on an iPad.

You might need to find your own unique place for documentation. That's okay. Be bold, and share it far and wide.

4. Organize Your Help Center

Swifttype support center
Swifttype makes it easy to find the search box in their help center.

Go to almost any online help center or knowledge base, and you'll notice something the same element: a prominent search box, right near the top of the page. Underneath that, you'll likely find an outline of documentation, with categories of articles to help users get started, dig into features, and solve common issues.

Paper documentation is the same. There's a table of contents, diagrams of the product, followed by pages describing how to use the product and then a set of troubleshooting guides at the end.

It's a format that works, one your users expect, too.

It's important to keep in mind the order of how you're presenting information to the user. If you start with an advanced tip right away, it could intimidate them. The best way to list information is in a chronological order starting with what they need to know as they're getting started, all the way through to the advanced tips and tricks at the end. help center's documentation walks you through each part of the app in order

Once you've listed common "Getting Started" information near the top of the page, the next thing to tackle is creating your categories—the sections of documentation that will explain about each feature. Use icons along with text to make it easy to browse, and feel free to organize stuff in a way that feels logical for your product. There's no perfect way—you can always experiment.

Dropbox support categories
Dropbox shows 12 categories on its support home.

Then, don't forget about FAQs—or frequently asked questions. If you've been answering questions for your product for quite some time, you're going to get a feel for the questions that come up the most. Listing a dozen of them both helps customers with those questions, and also educates new users who will likely read the FAQs as a way to learn more about your product.

Now, tie it all together with search. Most knowledge base tools include a search tool; if yours doesn't, add one with a tool like Swifttype. Users may browse through individual articles to learn more about your product, but when they need help they'll want it fast—and that's when search is crucial.

Swifttype includes a number of advantages that make it a great tool to include. It can predictively search as you're typing, to suggest related documentation before you've even finished writing what you need. Your team can also rank documentation in Swifttype, to make sure your best, most helpful articles and videos float to the top.

Tweak your layout and search, and your customers—and support team—will always be able to find what they need.

5. Surface Your Documentation

MailChimp support docs
MailChimp makes support docs accessible inside its app.

You don't want your documentation to join the ranks of never-read owner's manuals, something to throw out with the phone books. After spending the time to write tutorials and shoot videos, you'll want to see your support center be a popular part of your site.

Putting your documentation where users expect is half of the battle. You'll of course want to link to the knowledge base in the main navigation of your website—include it in the header or menus, as well as with the index in the footer.

Then, add a "Contact Us", "Support" or "Help" tab near the side or bottom of your website or app for customers to get in touch. With many knowledge base tools—or with a self-hosted help desk and Swifttype—you can have the support form ask the user what they're looking for first. It'll then search through your help center and offer documentation first, before letting them email your support team.

Squarespace support docs
When filling out a help request, Squarespace directs users to its docs before they're able to submit the ticket.

Your customers will still start to get in touch about questions you've already answered, so this is a chance to guide them back to the documentation. When answering questions, be sure to not only answer their questions but also link them back to the article so they get accustomed to visiting your help center and can hopefully head there first for a future question.

Another helpful practice the Zapier marketing team has started doing is mentioning our help center in the product lifecycle emails we send, reminding users where to look for help. Our marketing team also looks at the most frequently visited help articles to decide what we need to describe better to users. If there is a particularly high volume of requests relating to a particular help category, we'll set up campaigns to go over the most popular topics and explain them in greater detail.

Onboarding email example
Zapier's onboarding emails include links to our documentation.

That all makes sure users are aware of documentation, but how do you get people to visit it when they aren't looking for help? By making it fun. If you offer webinars, pre-recorded trainings, and tips and tricks on how to make the most of some of your product's features, people are going to want to stick around longer and explore. Make it fun for them to learn and they'll invest more time into understanding the product and have fewer questions later on.

6. Keep Improving Your Documentation

Helpful rating on support doc
Zendesk's documentation asks 'Was this helpful?' at the end of every article

Even if you've written great documentation, there is always room for improvement. So listen to your customers. Keep writing about topics they're asking about, and rewrite documentation that still doesn't seem solve users' problems.

Now that you have a structured knowledge base, it's time to circle back and see what's working—and what's not. Some knowledge base tools let readers vote on whether an article was helpful or not, while others let you see analytics of your most popular articles or the things users are searching for and not finding. You can even measure how many tickets were created from failed searches on your help desk.

Or, you could even ask people what they think about your documentation. Tweak your support form to ask people if they found what they needed, or if they needed more help. Ask them to pick a category for their question, so you can quantify how many people are asking the same questions. Then take those ideas and turn them into better documentation.

Rinse, repeat. "You'll never be done," says Highrise's Gallo. There are always new features to document, outdated videos to reshoot, better ways of explaining old concepts. But over time, you'll get closer and closer to documenting everything, and your customer satisfaction rising along with it.

Now Start Documenting!

Zapier help center
Zapier's help center, which features over 500 support articles.

These are some of the many tips we've learned the way at Zapier, while building a tool that integrates over 500 app. We've learned we must document everything, since there's far too many parts to each individual integration for any one person to memorize. We're continually working to improve our documentation, and experimenting with different ways to share info automatically with our users.

What makes it worth it all is when our documentation helps our users accomplish something great on their own.

"Being able to rewire the neurons in someone's brain so that they understand something they didn't understand before is extremely satisfying," Losh says. "Seeing (or hearing about) the 'click' when a bunch of concepts suddenly fall together and make sense never fails to make my day."

We couldn't agree more.

You can help customers help themselves with great documentation, then make it faster to answer other questions with a great customer support app and automations. But sometimes, the problem is actually your app—and if you listen to customer feedback and the questions they're sending your way, you'd find ways to improve your products and decrease support at the same time.

In the next chapter, we'll learn how to collect valuable customer feedback, and how to put it to work for you, with examples on what's worked for the Intercom team.

Go to Chapter 10!

Want to learn more about writing documentation? Here are some other great resources:

Written by Zapier People Ops Lead Jess Byrne, with contribution from Zapier Marketer Matthew Guay.


Take the Work out of Workflow

Zapier is the easiest way to automate powerful workflows with more than 3,000 apps.