Best practices: Developing content for your knowledge base Best practices: Developing content for your knowledge base

Best practices: Developing content for your knowledge base

Administrator Administrator

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 view in Zendesk 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 Support 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.

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.

On Suite Growth, Suite Professional, and Guide Professional, you can work in draft mode, and have others review your draft, until you are ready to publish your new article in the KB, see Working with drafts.

On Suite Enterpise plans and Guide Enterprise, Team Publishing makes it easy to get new and existing content reviewed. You can create new articles as a work in progress, then submit it for review (see Creating new content for review), or you can stage updates to existing articles and get them reviewed before you publish, see Staging content updates.

You might also consider a review by one final person--someone responsible for publishing. If you limit publishing to certain team members (see Setting agent editing and publishing permissions), they can review and approve all KB content before publishing it. On Suite Growth, Suite Professional, and Guide Professional, publishers can review and publish all drafts. On Enterprise plans, the publisher can review articles submitted for review and approve and publish them, see Reviewing, approving, and publishing articles.

Add comment

Please sign in to leave a comment.