Tips for creating a knowledge base

If you’re planning on creating a knowledge base or looking for tips on how to provide better information, this article is for you. I’m going to cover some of the different ways to create a knowledge base, paying particular attention to those that are part of a wider customer support centre. I’m also going to share some tips on how to write more effective support articles.

Knowledge base or online help?

Before we get into how to write help articles, I want to clarify what we mean by a knowledge base and how it compares to online help.

In terms of what the end user sees, there’s little difference between a knowledge base and a modern HTML5 help centre or online help. They should both have clear navigation, search capabilities and web articles that provide helpful information.

But there is often a difference in how they are created and in whether they are part of a wider customer service system.

Content Management System (CMS)

Arguably the most common way to create a knowledge base is to use a Content Management System (CMS). With this approach, you create your articles in the CMS’s built-in editor and publish them directly in the CMS. The software provides a simple editor and the web hosting, so everything you need to get your content online is in one place.

The most common CMSs that I’ve seen in use are dedicated customer support products, such as Zendesk and Freshdesk. These provide a knowledge base and extra customer service functionality, such as a ticket system for logging issues with the customer support team.

These customer support CMSs usually have basic What YouSee Is What You Get editors (WYSIWYG), so it is easy to create helpful articles. If you have ever written a blog in WordPressor on Medium, it is a similar experience. And just like those platforms, the content you write is hosted in the customer support centre. You don’t need to do anything else to get your content on the web and available to your readers.

On the plus side, a customer support CMS will usually have:

• User-friendly interface for writing and editing
• Additional customer support features
• A hosting facility.

The downside of these CMSs is that they lack some of the features that technical communicators need when creating content to scale. You’re unlikely to find features like content reuse, variables and filtering (more on those later) and there’s a good chance that you and your team will end up copying and pasting a lot of content. Or worse, writing the same content over and over, wasting your valuable time and making it more difficult and expensive to maintain and translate.

But these advanced authoring features are commonplace in many technical communication products.

And that leads us to another approach – using a technical communication tool to create a knowledge base.

‍Technical communication tool

Technical communication software, such as MadCap Flare and Paligo CCMS (Component Content Management System) are designed for creating documentation to scale. These types
of software have a much wider range of authoring features, including:

• Content reuse
  Where you can write content once, in one place, and reuse that same content in many different articles.
  
  
• Variables
  These are for when you have a particular phrase, such as a product name, that is needed throughout your documentation. You add the variable where you need that content, and then set the text that should be used in place of the variable when you publish.
  ‍
• Filtering or profiling
  This lets you mark content to be included or excluded in different scenarios. For example, you could include a paragraph for Windows users but exclude it for Mac users.
  ‍
• Single-source publishing or multi-channel publishing
  These features allow you to produce a knowledge base, print manuals, and other outputs, all from the same set of content files.

All of these are important features when writing large amounts of documentation. As you can write content once and reuse it in many places, it means your content is more consistent as there is less of it. As a result, it is easier, quicker and less expensive to create, update and translate.

On the other hand, technical communication tools do have some disadvantages when compared to a customer support system:

• More complex features that come with a bigger learning curve.
• Hosting is not included (or included at extra cost).
• The knowledge base does not have all the extra customer support functionality you get with a CMS.
• Collaboration can be more difficult – it may be that all contributors need to use the tech comm tool, or extra steps may be required to import their work.

But what if you need a knowledge base, customer support centre and advanced authoring tools? Is there a way to get it all? Thankfully, yes.

‍Technical communication tool publishing to a customer support CMS

‍There are technical communication tools that have the authoring features you need and the ability to publish directly to other systems. For example, Paligo CCMS can publish directly to Zendesk, FreshDesk, ServiceNow, Salesforce and more. Other products, such as MadCap Flare, also provide support for publishing to other systems. In that scenario, you can use the authoring tools to create the content and then publish it as articles in a customer support CMS. You get the best of both worlds but must invest in multiple products.

But the market is changing and some customer support CMS vendors are starting to provide content reuse features.

If you have made the decision to create a knowledge base, take the time to consider what you need to achieve and what each product can do. It may be that a combination of products will be the most cost-efficient option in the long term.

‍Understand the structural limitations

When you have decided how you are going to develop your knowledge base, you can start creating your articles.Depending on the approach you are taking, you will either create the articles directly in a CMS or you will create topics in a documentation tool.

The first thing you need to consider is the format that is required as many customer support products have a strict structure that must be followed. For example, some have a three-level structure of category, section and article. This has an impact on your information architecture, as all your content goes in at the article level and as a result, you don’t have the luxury of multi-level topics as you do in an online help system.

Let’s use Paligo content as an example of a technical communication tool. There, you can have a multi-level table of contents as shown in Figure 2, where there are four levels (including the publication title as one level).

In many customer support systems, there is a strict three-level structure of category, folder and article. Anything at a lower level would need to be a subsection of its parent article.

There’s no problem with using subsections in an article but you’ll need to plan your content so that the articles do not become too long. To handle this, you may find that you need to create more articles and add links between them.

With a dedicated technical communication tool, you’re unlikely to have these structural limitations. You will be able to create a ‘table of contents’ with content nested at many different levels. But if you are using the tool to publish
to another system, you will need to meet the structural requirements of the other system.

‍How to create helpful knowledge base articles

Once you have decided how you are going to create your knowledge base, you can start thinking about your content.

The first step to consider is what the knowledge base needs to achieve. The goal is to create articles that are:

• Easy to find via menus and/or a search facility.
• Clear and concise.
• Focused on one user need at a time.
• Linked to other relevant articles.
• Well-designed, with images and videos to support the text.ƒ Going to make self-service possible and reduce the demand on support staff.
  

After that you can start planning, creating and revising your content.

‍Start with the user

To write suitably relevant content for your users, you first need to understand who they are and what they are looking for. Some organisations employ user researchers, professionals who gather information about your product’s audience. But that's not always the case, and many communicators have to be proactive and resourceful, wearing many different hats in their day-to-day work.

If you need to do your own user research, here are some of the things you can do to get an insight into user needs:

• Speak with customer-facing staff.
• Ask designers and developers for their views - why did they create a feature in the first place?
• Look at support tickets and emails.
• Check social media and forums for mentions of your product.

After gathering the information, you should have a better idea of who your customers are, what different job roles and needs they have, and what sort of language they use. By talking to the designers, you should also get a good idea of what workflows the customers will need to follow to achieve their goals.

At this stage of the process, you will be better equipped to know what to write, what terms to use and what your customer’s needs are. The next step is to create articles that meet those needs.

‍Plan your content reuse

This only applies if you are using a technical writing tool or have discovered a CMS that supports content reuse.

Depending on the capabilities of the tool, you may be able to reuse entire topics, smaller snippets of content, or even individual words. The first step is to understand what the tool supports, then you can look for patterns in your content:

• Are there topics/articles that are required in multiple places?
• Do you have descriptions, procedures, images, that are the same in multiple places?
• Are there individual steps that are repeated?
• Is there content that could be reused, if only a product name was different, or a paragraph was hidden?
  You can reuse the content by using variables and filtering.

These are often good candidates for content reuse.

You should also consider how your writers will know that reusable content exists and where to find it. Some tools have search features for finding reusable content but in others, you will have to organise the snippets yourself. In this case, it is a good idea to come to an agreement with your team, otherwise you could find yourselves doubling-up on reusable content, which defeats the point.

Consider the titles and SEO

A common problem with knowledge bases can occur when articles have similar titles. For example, if all articles begin with “How to...”, the table of contents will have a long list of “How to...” entries, which makes it more difficult to scan.

It is better to try and front load the titles, so that the main subject of the article appears close to the start of the title.

You should also consider search engine optimisation (SEO),when writing your content. Aim to include the most relevant search terms in your main title and headings but don’t write anything purely for SEO purposes; always write for your audience and the SEO should pretty much take care of itself. Although you still need to add the "technical" parts that are needed, such as the description.

Some knowledge base tools have features for adding a metadata title and description specifically for the search engines. Make sure you use these. Again, it is a good idea to use the main search term in the description, and also synonyms.

Focus on one user need per article

Try to make each article in your knowledge base focus on one user need, so that it has one purpose. For example, if your user wants to know how to replace a component in a product, the article should be about replacing the component and nothing else. If there is additional information that they will require, mention it but provide the detail in a different article and use links to guide the user to it.

Keeping your articles focused on one topic makes it easier to keep the information clear and well-structured. It will also convert more easily to the topic-based approach used in many technical communication tools, should you ever need to export it.

Treat every article as the first article the reader has seen and make sure to include links to other relevant articles, as mentioned earlier. This way, you can guide them to all the information they need to understand the article fully.

Also, remember to only include links to articles that are relevant to completing a task. Otherwise, you might overwhelm the reader with too many choices. Try to keep them on the path that leads to completing the specific task that the article covers.

‍Include context as well as instructions

When you write articles that contain step-by-step instructions, make sure you give the reader enough context. The reader needs to know what to do and in what order but also when they should do it and why. If you add this extra context at the start, it will help make your article less reliant on information in other articles. Also, adding an example or two always helps.

‍Think about usability and accessibility

There are many things you can do to make your articles more accessible to people who use screen readers and other assistive technology, including:

• Add descriptive “alt text” metadata to all your images.
• Make sure videos have captions for dialogue and that there is a text version of the information available in the article too - that’s also better for SEO.
• Consider the use of colour and make sure it contrasts enough.
• Use accessible fonts.
• Use meaningful text for hyperlinks, not “click here”.
• Avoid using tables for controlling the page layout. Use them for data, not paragraphs of information. Also, try to keep tables simple and consider how they will appear on mobile devices.

You can find links to some useful accessibility information in the references of this article.

‍Iterate!

Once your content is published, keep track of user responses to it. Customer feedback on your articles will let you know if there are parts that need extra work or changes, to avoid confusion.

It’s also important to communicate with Customer Support, so that you get a good idea of any common problems. This can help highlight issues with: the content, common misconceptions about the product and areas where more detail is needed.

This vital information will help you when planning, prioritising, reviewing and writing your content updates.

‍Further opportunities

If you are interested in exploring different roles in technical communication, writing knowledge bases content can be a great start. This ability and skill set puts you in a good place to learn about a product and its customers, and that can lead to other roles. I have worked with technical writers who have become customer support agents, customer success managers and product evangelists. Personally, I enjoy working in customer support sometimes and find the opportunity very useful for user research because there’s no better way of finding out about customer needs than speaking directly to them.

References

Accessibility for teams. ‘Is there enough contrast between text and its background color?’ Accessibility for teams. https://accessibility.digital.gov/visual-design/color-and-contrast/ (accessed 16 July 2021)

Content Design London (2020) ‘Readability Guidelines’. February25, 2020. https://readabilityguidelines.co.uk/content-design/links/#1-make-link-text-meaningful (accessed 16 July 2021)

Dutta, H. (2021) ‘Best tools for SEO writing in 2021’. Boostability. June2, 2021. https://www.boostability.com/content/best-tools-for-seo-content-writing (accessed 16 July 2021)

Eggert, E. (2019) ‘Tables concepts’. Web Accessibility Tutorials.July 27, 2019. https://www.w3.org/WAI/tutorials/tables/(accessed 16 July 2021)

Karpinska, K. (2020) ‘What is the Content Blocks EAP and how do I use it?’ Zendesk. May 20, 2020. https://support.zendesk.com/hc/en-us/community/posts/4409217123354-What-is-the-Content-Blocks-EAP-and-how-do-I-use-it-?page=1 (accessed 16 July 2021)

WebAim (2020) ‘Typefaces and Fonts’ WebAim. October 27, 2020. https://webaim.org/techniques/fonts/ (accessed 16 July 2021)

‍

This article originally featured in the Autumn 2021 issue of Communicator, the journal of the Institute of Scientific and Technical Communicators.