top of page
  • Writer's pictureAnne-Marie Traas

Strategies for Effective Internal and External Documentation


Help documentation isn’t just a repository of information for when your team members get stuck. Nowadays, your knowledge base also serves as the foundation of your AI-driven tools.

Let’s explore how internal and external knowledge bases can be tailored to serve your company's distinct purposes, ensuring your customers and employees have the information they need right at their fingertips.

The difference between external and internal documentation

You know what a knowledge base is: a library of information relevant to your organization. 

But what’s the difference between internal and external documentation?

  • An external knowledge base is for people outside your company, like customers and leads. The main focus is teaching them how to achieve their goals with your product and answering common questions. 

  • Internal knowledge bases are for those within your organization. A customer doesn’t need to know the steps support uses to troubleshoot a possible bug or a timeline of product releases. But it is certainly helpful to have this information documented somewhere.

Most customer support teams maintain internal and external knowledge bases to ensure everyone has easy access to the information they need. 

One of the advantages of keeping both on Zendesk Guide is that it enables your support team to search through all documentation at once from the same place when they’re working on tickets. All you need to do is publish articles with different access levels, so some articles can be viewed by customers and external users, while others require agent access to your Zendesk instance. 

But how do you know what to put where? When does it become too much information versus not enough?

How to decide what to share and with whom

It’s always challenging to draw the line between providing as much information as necessary, without overwhelming customers or employees. 

How do you make that call?

There are two camps in the debate of “too much versus just enough:”

  1. Some believe that a customer can never have enough information, provided it is structured for easy discovery and is written to the technical or educational level of the target user.

  2. Others say you should only provide the specific information that a customer is asking for via short-form articles that answer a specific question. For example “What payment methods do you accept?” can be answered in a single short paragraph: “We accept all major credit cards, along with PayPal.”

1. Supply comprehensive information

The goal here is to provide so much information that your customers could theoretically find everything they could possibly need.

Comprehensive documentation is often designed as a “complete guide” to a specific process or feature. 

This is doable, but it takes some work: 

  • Information must be well-organized and broken into clearly defined sections so your readers don’t get lost. 

  • Each article should also have a table of contents allowing the reader to jump to the exact information they're looking for while also drawing upon information they didn’t know to look for. 

  • It typically works best if you have a fantastic search (maybe even an AI-powered one) that picks out the relevant information for you. 

2. Provide just the essential information

A just-the-essentials style knowledge base provides the exact answer your reader is looking for 95% of the time.

It fulfills a specific function and does that well. Ideally, your customers get to the knowledge base when they’re looking for one piece of information, they don’t have to spend much time looking for it, and they get back to your product as soon as they find it. 

The only challenge here is that it requires them to be much more proactive with further learning. Maybe there’s an extra tip or trick they’d get a lot more value out of—that they’ll never see. 

3. Compromising between the two

It doesn’t have to be either/or. You can serve both needs in the same knowledge base. 

Think of it like having your cake and eating it too. 

You get the best of both worlds: quick answers when you need them, and comprehensive articles for when you have more time to delve deep.

You probably don’t need a guide to explain why your product doesn't support Internet Explorer. Spoiler: it was discontinued in 2016 and even Microsoft no longer supports it. That can be addressed in a simple one-paragraph FAQ. 

More technical concepts could require a more in-depth explanation and annotated screenshots. 

The best method is to try out a variety of types of documentation (both internally and externally). Then you can use analytics software to monitor how often different article types are visited and see how they are rated by your audience. If they show a clear preference for a particular layout, roll with it!

Guidelines for what to share and with whom

Picking a general philosophy is all well and good but it doesn’t help actually decide what to share and with whom. 

In part, that’s because it’s really all dependent on your audience.

Here are a few general rules of thumb for sharing information to help you decide where to put it.

  • Speak to the lowest education level of your target audience. Unless your target audience are engineers, don’t throw technical jargon at your customers. You want them to be easy to understand. A help center for a no-code platform isn't going to dive deep into the engineering that makes it work. Customers just want to know how to do the thing.

  • If it creates more questions than answers, don’t share it. This should help decide what to include in articles about troubleshooting common issues. If you get many issues that can be answered by informing the customer which browsers are supported, document that externally. You probably don’t need to document edge cases that impact one in a thousand customers though. 

  • Follow ethical privacy practices. Don't use a customer or employee's name, logo, image, or other personal information unless they have specifically given you permission. This goes for screenshots, too. Use dummy accounts whenever possible. If you want real-looking information, invent a fake company.

  • Does it need to be an article? Sometimes, you only need a line or two. Does this justify creating a new document that needs to be maintained? Could you present the information differently? It could be part of a larger FAQ document containing all the short questions. More importantly, if you need to document something like how to log in, the right solution might be implementing product improvements rather than trying to document yourself out of poor design choices.

9 pro tips for managing your internal and external knowledge bases

Here are some great tips for how to structure and maintain your documentation. 

Content creation

  1. Keep content well-organized. Group series of articles about the same feature in the same section. Make sure your categories are simple and high-level enough that your customers know what to expect. If sections get too overwhelming, break them up. The easier your help content is to find and navigate, the more effective it will be at actually solving your customers’ issues. 

  2. Settle on a tone and stick with it. Consistency makes a difference in how your customers engage with your content. That goes for your fake company information used in screenshots too! Your whole help center will feel more professional, credible, and trustworthy. 

  3. Use the correct terms. In external articles, refer to features by their actual names and not the shorthand terms you might use internally on Slack. This helps train customers to use the correct terminology when seeking help, creating clarity and preventing unnecessary back-and-forths. In internal docs, you might benefit more from using your internal shorthands, if they’re so widespread in your company that that’s what agents will look for. You want to simplify the load as much as possible. 

  4. No walls of text! Nobody wants to click on an article and read a thousand-word essay. Use paragraphs and formatting to break up your text, and include images and gifs (where appropriate) to separate passages further. Your article should be inviting, not daunting. This is equally as important in external and internal docs. Agents typically reference internal docs while working on tickets, so they’ll always skim. 

Maintenance and revision

  1. Regular updates and reviews. Outdated information leads to confused and exasperated customers contacting support, so taking the time to audit your help center and updating its content with every release is crucial. Zendesk’s built-in reporting can already provide basic information to work with, like how many views an article gets and when something was last updated. Use these to organize a review. 

  2. Catalog your library. It helps to know how many articles you have and on what subjects, or which articles link to which others. If a feature changes, you can quickly identify which articles will require an update without relying on memory or, worse, scanning each article individually (been there, done that). A tool like Help Center Manager works wonders here.

  3. Track article visits to identify trends. Maybe it's just a well-written article that your audience appreciates. But sustained visits to particular articles could indicate that something isn't clear with how that feature works. A sudden spike in visits to a certain topic could indicate a bug. Stay open-minded and curious about your readers’ reading habits. You can even collect feedback from each article (in addition to the helpfulness rating) to understand these numbers better. 

  4. Check your search history. Check what your readers are searching for. This is a great way to identify gaps in your knowledge base. If you come across searches that return no results, consider creating an article for them. One of the quirks of Zendesk Guide is that it only searches the first 10,000 characters of an article, so if you have important and relevant content past that, it might never show up in the results. 

  5. Use the right tools. Dedicated tools, like Help Center Analytics, help measure self-service performance, the helpfulness of your information, and the engagement of your audience. It’ll also help you track the paths that visitors go through when they’re navigating your help center—so you can really see which articles drive ticket creation. 

Maintaining help documentation over time

Managing a knowledge base isn’t the easiest task. It requires attention to detail, organization, product knowledge, and no small amount of writing skill to fulfill the important task of keeping customers and colleagues in the loop. 

Some companies have teams of people to create and maintain their content. Others use collaborative efforts from multiple departments. And in many companies, there’s a sole person who handles everything!

But there are tools to make this so much easier. Swifteq has a suite of dedicated help center apps to assist the inner librarian in you.

Help Center Manager streamlines content management across multiple knowledge bases. Help Center Analytics offers deep insights into what users are searching for and how they interact with the content. Help Center Export provides robust options for backing up and exporting content. 

Sign up for a demo to see these tools in action. 


Commenting has been turned off.
Start your week with great quality articles on customer support

Thanks for submitting!

bottom of page