Best practices: Developing content for your knowledge base Follow

all plans

There are many ways to manage the content creation process for your knowledge base (KB). The size of your team, type of business you have, and whether you are creating internal or public-facing content might determine your process.

These best practices, based on feedback from Zendesk users, are meant to offer guidance and help you build a valuable knowledge base.

Identify a knowledge base owner

Be sure to identify an owner for your knowledge base. Whether this person is dedicated to the KB or wears many hats, you need one person on your team who is responsible for the KB. The KB owner is the contact for the team and can ensure that content is created and is consistent.

The KB owner should regularly monitor and check the list of issues that need KB documentation. This helps ensure that new content is created in a timely manner and that existing content is up-to-date. Depending on how the team is identifying issues, a Zendesk Support view is probably a good way to get a snap shot of KB issues. The KB owner can then prioritize, schedule, and assign content accordingly.

Having a KB owner is also a great way to make sure that your KB content meets standards and is consistent and thorough.

Note: Be sure to check out the community discussion in our forums How do you manage KB articles.

Establish a process for flagging issues for the knowledge base

Support agents work closely with customers and understand their issues, so identifying issues for the KB should be a standard part of each support interaction. Be sure you have a process for agents to flag issues that require new or updated documentation.

At Zendesk, our customer service team uses a specific tag to flag tickets with issues for the KB. Alternatively, some of our customers add a custom field to their tickets so that their agents can select Yes or No for KB updates.

Community tip from Cheryl at ViewPath! My end goal will be this: (1) Tier 1 and Tier 2 agents suggest topics to our Technical Writers, (2) Technical Writers write the document, (3) Document is submitted back to (probably) a Tier 2 agent for review to make sure the topic is appropriately covered.

Agents should always search for existing documentation to avoid creating multiple versions of the same issue. And when there is existing content, the agent should check to see if it needs updates or improvements, and flag it if so. After a while this will become standard support process, and agents will identify content needs naturally and according to demand.

If possible, go one step further and build content creation and maintenance into your support workflow as well. For example, encourage agents to take time after working with a customer, while the details are fresh, to make quick KB updates or at least get started on larger issues. If that's not possible, at least you know the need has been recorded in the ticket and the team can handle the KB update via another process.

Note: If you are just starting a knowledge base, you might want to comb your tickets for issues to populate your knowledge base. For more information, see Best practices for finding customer issues to start your knowledge base.

Determine who will write content for the knowledge base 

If you don't designate people to write content for your KB, then chances are no one will write content for your KB. Creating KB content has to be a priority, and part of the regular responsibilities for specific people or a group.

Some teams have dedicated writers who are technical writers or members of the support team. Some teams have SMEs (subject matter experts) who create content. Other teams rely on their support agents for content creation. If your agents are responsible for content creation, make it part of their workflow. You might also try rotating writing responsibilities among the agents.

Community tip from Todd Zabel! We have a small Support team (5 people), so we all wear multiple hats. I have created the style guidelines and taxonomy, and I assign writing projects to specific members of the team based on their subject matter expertise. Each month, we do a review of a cross section of articles. Each member of the team picks 1/5 of all articles from a spreadsheet to ensure that each one complies with our guidelines, is current, is not redundant of other content, contains good multimedia content, and has been syndicated to our social channels for maximum visibility.

Your KB authors don't have to have "writer" in their titles. But make sure updating the KB part of someone's regular job.

Establish standards for authoring quality knowledge base content

Regardless of who is creating the content (support agents, technical writer, or someone else), it's important that articles are clear, concise, and consistent. If users can't easily find answers in your KB, they might get frustrated and file tickets instead.

Here are some general tips for authoring KB content so that it's easy for users to find and use:

  • Develop a template for your articles. A template makes it faster and easier to create content. No one likes facing a blank page. Develop a template with designated sections to fill in, so that authors include the right information and not extraneous information. A template also ensures your articles are consistent and users know what to expect.

    Community tip from Kirk! Yes, two core templates are - PERC (problem, environment, resolution, cause) for issues and Question - Answer - Overview for FAQ's. Lists can be in bullets, directions in numbered and lettered steps. The other "template" is direction and monitoring - each article should be a short solution to 1 core issue.

    For more info on Kirk's recommendations, and for tips from other users, see the community discussion in our forums Do you use a "template" to author your KB docs.

  • Keep articles, short if possible, and divide content into sections. Articles should be short enough for users to quickly scan to see if the info they need is there. You don't want to overwhelm users with too much information in one article. And for longer articles, be sure to break content into sections with clear headings.

    At Zendesk, we recently broke up a long article about "users." Specifically, customers were having a hard time figuring out how to change their account owner. The info was in this long article, but when users found the article in search, they didn't know the info they needed was buried somewhere in there. Breaking up the long article into shorter topics helped solve the problem.

  • Use clear, action-based titles. Users tend to look for articles in your KB when they want to accomplish a task. Be sure your articles are clearly titled with the action or task that is documented. Vague and general titles make it hard to users to know if the task they need is covered.

  • Use bullets and numbered lists. List items and steps are much easier to scan and follow when they are broken into bullets or numbered lists. And be sure to use the right kind of list--use bullets for lists that don't have an order, and use numbered lists for steps that have to be completed in order.

  • Define terms and jargon. Make sure you define terms in your articles, or point users to a resource, such as a glossary, that defines key terms for your product or business.

    For advanced concepts, consider linking to an article that explains the concept. You don't want to include a lengthy explanation for a concept if users don't need it. But for those who might need it, point to reusable content that provides more information.

  • Link articles to show relationships. Be sure to link related articles. This will help users find all the information they need to solve their problem. And it might help them answers some questions they didn't know they had.
    Note: In Zendesk, when you change an article's title or move it, you don't have to update links. When you make those changes, the article ID remains the same, so the links are still valid.

Require technical reviews before content is published

Users trust that they are getting reliable information in a company's knowledge base. But if they find too many errors or inconsistencies, they won't trust the info and they won't use the KB. So it's important to have content reviewed before it's published.

Note: In Help Center, you can work in draft mode until you are ready to publish your article in the KB. Draft mode makes it easier to get content reviewed. For more information, see Working with draft articles.

KB authors should schedule a subject matter expert (SME) to review articles for accuracy and thoroughness. Multiple review cycles or multiple reviewers might be necessary for complex topics. A lot of Zendesk users rely on peer reviews, where agents review articles by other agents and provide valuable input. This is also a good way to share knowledge.

Community tip from Andrea Saez at Amilia! Always a good idea to have both a Technical Writer and an SME (or Product Expert) that knows the platform inside-out to double check the entire KB, and maybe even have a Marketing person give it a go to make sure it's not too on the techy side.

You might also consider a review by one final person--someone responsible for publishing. If you limit publishing to certain team members, they can review and approve all KB content before publishing it. At Zendesk, our internal KB articles are created in a special staging area. An operations manager must review and approve articles before publishing them in the internal KB.
Note: In Help Center, if someone has permission to create articles, they can also publish them. So if you want to require approval before publishing you can establish a manual process.


Have more questions? Submit a request


  • 0

    This is a good article, but are there any best practices on retiring knowledge articles?

  • 0

    Hi, Nancy.

    Here in our company articles are written by different levels and support teams, and has one year validity. 5 days before article expires, the tool sends notification to the author/owner that they need re-validate the contents before re-publishing the article or otherwise they need to retire it. Problem is author/owner don't really do that, so we need to chase them. There are instances that author/owner already left the company leaving us with no idea who to contact. That's the time we retire the article, when no one can be contacted to update it.

    We also consider when article has not be updated ever since it was created (more than 2 years). Number of times article was used can also be considered, if article has only few used/views and wasn't updated for quite sometime, we retire the article.

    I hope that helps.

  • 0

    We've been having an issue on our team trying to create an effective workflow for turning tickets into documentation. We created a simple checkbox ticket field, "Needs documentation", and a view for all tickets with this checked.

    The issue we're having is that we can't always take tickets out of the queue after we've created docs for it. We have limited resources for docs--I'm the only tech writer on the team--so sometimes, tickets will move to 'Closed' status before I'm able to finish docs for it. Once that happens, we can't uncheck the box to remove it from the queue. Do you have any suggestions (besides working more quickly/getting more writers, hah)?

  • 0

    Hi Quan!

    The first thing that sprang to my mind is the Ticket to Help Center app. This app allows you to select any comment in a ticket, edit (if you wish), and post as an article to any section in your Help Center. 

    You could set up a restricted Section for your drafts and send these "future docs" there using the app. Then you can edit them as you have time without worrying about the tickets getting archived before you get to them.

    The only caveat is that this app is not officially supported, so if it breaks at some point you'll need to rely on the Community here or your own developers to fix it. 

  • 0

    Hi Jessie,

    Thanks for the feedback! I did just install the Ticket to Help Center app based on one of your comments on another post/article. But thanks for the feedback here, too. Your suggestion would effectively move the documentation queue from the Zendesk Support interface into the Help Center/KB interface, allowing me to update the queue as needed. This may be exactly what I'm looking for! Thanks again!

  • 0

    Terrific! I hope it works well!

Please sign in to leave a comment.

Powered by Zendesk