☰ Menu
+1 866.606.7247
×

Popular Searches

Technical Writing Documentation Services Training Methods User Documentation Consulting Services

10 Reasons Why Your Knowledge Base
Should Have Single-Topic Articles​

As companies move away from producing conventional user guides and service manuals toward using online knowledge bases (KB) to provide product help and other support information to their customers and internal support agents, they often turn to Contiem for help.

Generally, it is not a good idea simply to convert an existing document into a web-based format (HTML), leaving the content and structure of these long documents as is. However, it requires more effort — and cost — to restructure information into short, single-topic KB articles, and the previous documentation structure worked fine on paper, so it should work fine online, too, right?

Actually, no. The unified document structure that might work on paper or in PDF doesn’t really work online.


An Example

Recently, a Client looked at the ongoing KB maintenance effort and wondered if it wouldn’t be faster, easier, and cheaper to maintain a few long, comprehensive articles — similar to traditional user guides — rather than the hundreds of shorter, single-topic articles that existed in their KB.

The Client’s KB is a public website designed to help its customers solve their own problems and to help the Client’s customer support agents assist customers. It’s a key component of the overall Client customer support strategy. As such, its primary design consideration must be user needs and their experience: Why do users come to the KB and how are they likely to feel when they arrive?

KB users are usually trying to solve a problem and are likely to be anxious and frustrated, more so if they cannot quickly find answers. The KB should do everything possible to relieve — or at least not intensify — those emotions. That means it must present the right information to the right users in the most effective, efficient, and usable form.

1. Users Prefer Short Articles

Extensive web usability research shows a clear conclusion: people prefer to read short articles. Therefore, to the extent possible, each KB article should cover a single, discrete topic. We’ll call these focused articles “simple” articles and call articles that cover multiple topics “complex.”

Simple articles help readers find and retrieve the information they need quickly and easily:

  • Users read only about 25% of the text on a web page. They scan and skim until they either find the information to solve their problem and read it, or they give up and call customer support. Simple articles cater to user attention spans.
  • Users are goal-oriented. They are generally looking for one specific piece of information: how to solve their problem. They do not want to wade through information that is not relevant to their immediate need. They want to quickly find what they need and move on.
  • Users are intimidated by and likely to abandon long, scrolling, complex articles. They become overwhelmed when there is too much information that they must scan through to find the piece they’re looking for.

A simple article that answers one question is more effective than one that tries to answer every question about a subject. Consider the customer who needs to know how to add someone to their account. They see a complex article titled “Users” or “Accounts.” First, they can’t be sure that the article includes the information they’re looking for. Second, they will have to scan/skim through a lot of irrelevant information to find the one piece they want. Compare that experience to them seeing a simple article on “Adding a User to Your Account.” They immediately recognize that it contains the information they need, and there’s no irrelevant information to wade through.

2. Improved Usability

Simple articles allow for specific titles that make the KB easier and faster to use.

Titles are used as the text in the navigation links that customers use while browsing the KB. The more specific the title is, the more confident the user can be that the article is one that they either do or do not want to read. As in newspapers, we look at the headlines first, and only if the story is interesting and relevant to us do we decide to read the rest of the article. The ability to quickly make this decision is key.

Because complex articles cover multiple topics, they cannot have specific, detailed titles. Vague and general titles make it hard for users to know if the article covers what they need. Users get bogged down clicking on vague or misleading links, not knowing what they’ll find. Once they get to the article, they quickly lose interest in then having to scan and scroll a long page to see if they made the right choice.

Think about a customer who is seeing a trouble message on their device. They want to know what it means and what to do about it. A title for a complex article such as “Using Your Device” doesn’t tell them if the article contains any information on trouble messages. To find out, they’ll have to sift and scroll through all kinds of other information—like how to use function A, turn off function B, or 20 other topics related to the device. Even if the article includes an in-page table of contents (TOC), they’ll still have to search that TOC trying to find the topic they need. On the other hand, a simple article title such as “Fixing Trouble Messages” is much more useful.

3. Improved Search Results and Search Engine Optimization

The top priority for a KB is searchability. Google has spoiled everybody. When users know what they’re looking for, they expect to be able to type in a keyword and find an answer. If the KB search produces poor results, customers either won’t use the KB — instead using more costly call, email, or IM support services — or they’ll struggle and become more unhappy and frustrated than when they arrived at the KB with their current problem. Good search functionality and results are just as important to the support agents who use the KB to assist customers.

Benefits for Search Engines

Explaining how search engines and search engine optimization (SEO) work is outside the scope of this discussion. Basically, search engines, both on the Internet and internally in the Client KB, consider a combination of factors to determine an article’s relevance to a user’s search keywords.

Two of these factors are the article title and introduction. Article titles should:

  • Be short, descriptive, and unique
  • Contain the main keywords relating to the article content
  • Clearly differentiate the article from other articles
  • Make sense when taken out of context


Introductions should also contain the main keywords and reflect the article content. Simple articles allow for more precise titles and introductions that contain specific keywords. Because complex articles cover multiple topics, it’s impossible for the title, introduction, or content to focus on specific keywords. The multitude of potential keywords makes it harder for search engines to figure out what the article is really about and, therefore, how relevant the article is to the user’s specific search term. This lowers the article’s relevance across all searches except one where the user happens to use the exact words in the article title.

Benefits for Users

The article title and beginning content are also crucial for the usability of search results. Internal KB search results display the article title and some random article content. External search engines vary in how they decide what article content they show in search results, but they all look at the top of the page content. From this limited title/content information, the user must be able to determine if an article is relevant to their problem.

Consider a user who wants to know how to delete a rule in the Client application, so they search the KB for “delete rule app.” Because we have a simple article covering only this topic, the first search result they see is:

  • Delete Rules in the Client App … Add or Change Rules in the Client App Delete Rules in the Client App… Easy Deleting a Rule Careful! Once you delete a rule, it’s gone.


If they use Google, the results are even more informative:

  • Delete Rules in the Client App https://www.client.com › Support › Client › Rules in App Careful! Sign in to the Client app for mobile devices. On the Overview screen, tap the Automation icon (arrow over two dots). On the Automation screen, there are two ways you can delete a rule. In the confirmation box, tap Delete to permanently delete the rule, or tap Cancel to keep the rule.


If we instead had one complex article on using rules in general, or on using the app in general, or even on using rules in the app, we can’t say where that article would display in the search results list, but the result would look something like this:

  • Using Rules in the Client App Use Rules in the Client App … Manage Your Thermostat with the Client App… Using Rules in the Client App


While the user is likely to click on this result, they do so with uncertainty. They can’t know if the article contains what they need, they’re only hoping that it does. Once inside, they’ll have to scan/skim through the content to see if it covers deleting a rule.

Good results in external search engines are also important because they reach customers who may not be aware that the Client KB exists and they draw web traffic to the Client KB site.

4. Better Linking

Simple articles offer more opportunities for more precise and extensive linking within the Client KB.

Like titles, links are used by search engines to determine relevance in search results. Generally, having a lot of specific links within and between a lot of specific articles increases each article’s relevance to specific keywords. Having a smaller number of complex articles means fewer links and lower relevance.

As discussed previously, the Client KB navigation uses article titles as link text. Thus, the same benefits provided by having specific, focused article titles also apply to links.

In each article, links to other articles in the same category appear in a bar on the left. Links to related articles as defined by the author appear at the bottom of the page. Both link sets let users easily jump between topics without needing to perform another search. They also alert users to other articles they might not have known existed otherwise.

We want to encourage users to explore the KB, not just to solve an urgent problem but also to learn how to use the Client service in general. While a user is trying to satisfy an immediate need, they may see links to other articles that they would find helpful once their current problem is resolved. Specific, focused links help to encourage this exploration. Without a pressing need, almost no one is going to click a link for “Using the Client Controller” so that they can browse through the content to see if there’s anything of interest in it. But a user who sees a link to “Change Do Not Disturb Settings for Your Client Controller” might think, “What are those settings? I didn’t know they existed. What do they do?” and then read the article.

The more places we can link to an article, the more likely the article is to be found, either through search or through browsing. Having a higher number of simple articles means there are more places for us to present links.

5. More Useful Site Metrics

Site metrics are tracked individually for each article. Metrics allow Client managers to track all kinds of information about how customers are actually using the KB, including:

  • Which articles are accessed the most — identifies areas where customers are having the most difficulties.
  • Which articles are viewed the least — identifies articles that may not be needed anymore or are not properly indexed and so can’t be found.
  • How users get to an article (from a search engine, internal link, etc.) — evaluates how effective the KB is at channeling users to the information they need.
  • How long users stay on a page — indicates whether or not users are finding the page content relevant.


The more focused the article content is, the more useful the metrics are. Knowing that 10,000 users viewed “Using the Client Controller” this month doesn’t tell us anything about the problem they were trying to solve. Knowing that 2000 users visited “Change Sound Settings for Your Client Controller“ tells us that a good number of customers want to be able to change the device sounds and can’t figure out how to do it by themselves. Is the function too buried in the device menus? Are installation technicians not explaining this function? Maybe there too many sounds coming from the device. We couldn’t formulate any questions like this just from knowing the number of visitors to a complex article because we have no way of knowing what they looked at within it.

6. More Useful Site Feedback

Every Client KB article solicits feedback from users via a “star” rating system and comment form at the bottom of the page. Comments are limited to 100 characters, so if a user is unhappy with an article, we can’t get much specific information about why. Also, many users will quickly click a star, but they won’t take the time to type comments to explain their rating.

Consider an article that a user rates as two stars out of five, with no comments. For a simple article like “Change Sound Settings for Your Client Controller,” we know exactly where to go to see if the article can be improved. For a complex article like “Using the Touchscreen Controller,” we have no way of knowing which part of the article the user was looking at and found unhelpful, so we lose the opportunity to make specific improvements.

7. Better for Support Agents

The Client KB is a vital tool used daily by Client support agents. Customers may be the primary audience for the KB, but agents run a very close second. They search and browse the same articles that customers do, plus they have access to hundreds of agent-only articles that customers never see.

All of the benefits we’ve discussed so far in relation to KB usability for customers apply equally to usability for agents. In fact, usability may be even more important for agents. If a customer can’t use the KB, they give up or they call support. But if an agent can’t use the same KB, the customer’s problem doesn’t get solved. If an agent can’t use the KB quickly and efficiently, that call lasts longer, costs the company more money, and takes up more of an already-upset customer’s time.

Simple articles let support agents direct customers to the exact Client KB article that contains the answer they’re looking for. When a customer calls the Client for support, the support agent often ends up emailing the customer a link to one or more KB articles related to their issue. Simple articles allow the agent to supply links that go directly to the information that the customer needs. Contrast this with a complex article where the agent would send the link but also need to explain where to go within that page to find the relevant information. It’s the difference between “Go here” and “Go here, then click this link at the top of the page, then scroll down to where it says [abc].”

8. Better for Authors

Simple articles are easier and faster to write, revise, and manage.

Consider how much time it would take to write a complex article titled “Using the Client App.” Where do we start? We must create an outline of all of the “App” topics we can think of, take screenshots of all the app screens, explain all the app functions and options, and write a history of the app — all things, by the way, that are useless to the customer who just wants to know why the app won’t install on their device. Some topics will need research and others won’t. Some topics will be completed before others. Different topics will need review by different subject matter experts (SMEs) or managers.

If we instead write multiple simple articles, each covering a single topic, we can:

  • Easily focus on just that content.
  • Split a group of simple articles among multiple authors who can work in parallel and complete the articles faster.
  • Better balance the workload by assigning a mix of harder and easier articles to each author so that no author is overwhelmed and all articles get completed around the same time.
  • Track and manage each article independently rather than trying to track individual sections within one article.
  • Send articles out for review as soon as they’re ready and only to the appropriate reviewers for that article.

9. Better for Reviewers

As stated above, different topics will need review by different subject matter experts (SMEs) and managers. For a complex article covering many topics, the author would need to send out the entire article to all reviewers and take the extra step of communicating to each one which parts of the article that particular reviewer should review. This increases the possibility of confusion or misunderstanding about what needs review, which in turn increases the chances of content that should be reviewed being missed and content that doesn’t need review being reviewed in error. Contrast this with simple articles where we send each article only to the appropriate reviewers and tell them to review the whole thing.,/br>
Reviewing KB articles is not at the top of many reviewers’ priority lists, so we want to make it as painless as we can. To that end, we want to avoid:

  • Confronting reviewers with a long, complex article that contains information that they don’t need to look at but that they must still wade through. Simple articles are less intimidating, contain a manageable amount of information, and don’t contain distracting, irrelevant content.
  • Making reviewers have to think about what parts they’re supposed to review and what parts they can ignore. Reviewers can review one entire article at a time. They don’t have to refer to separate instructions to identify which parts need review.
  • Making it harder for reviewers to schedule time for their reviews and return their feedback. One long article either must be reviewed in one sitting or the reviewer must divide it into sections and keep track of where they start up and leave off. They must also wait until their review of the entire article is complete before sending it back to the author. Simple articles can be completed individually, in smaller time windows, and returned as soon as each is done.

10. Easier Saving and Printing

Users often bookmark web pages or save them to PDF for later reference. Some users still print pages, especially for information that needs to be used away from the computer. Simple articles help these users by letting them easily bookmark or print — to paper or PDF — only the content they need.

For those who print, we don’t want them to waste time, paper, and ink printing a long, complex article when all they want is one section of it. The customer could restrict printing to specific pages, but they would have to figure out which pages the relevant section appears on within the total page count when rendered by their browser. There is no easy way to do this; they must guess, see if their guess is right, guess again, and so on. Simple articles let us avoid this issue.

Bibliography

Listed below are reference materials related to the principles, standards, and guidelines for KBs and modular documentation.


About Contiem

Contiem has been the trusted content partner of choice for companies and organizations such as American Express, the U.S. Federal Government, The Home Depot, Cisco Systems, UnitedHealthcare, eBay, Facebook, and many more.

When you engage Contiem, we take the time to listen and develop an in-depth understanding of your immediate needs and longer-term challenges. Then, leveraging the capabilities that make us unique, we will provide a best-in-class, client-focused solution designed to achieve your business goals.

Experienced in a host of authoring software and with a wide variety of industries, we specialize in delivering a blend of services for documenting products and processes, training development, translation and localization, and content management.

Whether you need a complete training program to augment a new product or service, or you require job aids for internal learning, Contiem has the experience and skills to deliver the results you are looking for.