More and more companies are moving away from producing conventional user guides and service manuals toward using an online knowledge base (KB) to provide product help and support information to their customers and internal support agents.
While Orbis Technologies helps clients to make this transition, questions sometimes come up about why it’s 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. After all, 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. In this article, we’ll discuss the reasons why, using a client’s existing KB as an example.
Recently, we had a Client who looked at their 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 exist in their current KB.
The Client KB is a public website designed to help Client customers solve their own problems and to help 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? Client KB users are usually trying to solve a problem and are likely to be anxious and frustrated. The KB should do everything possible to relieve—or at least not intensify—those emotions. That means it must focus on satisfying user needs.
To meet these goals, the KB must present the right information to the right users in the most effective, efficient, and usable form.
Extensive web usability research shows, “The conclusion is clear: people prefer to read short articles.”1 Therefore, to the extent possible, each KB article should cover a single, discrete
topic. For the purpose of this discussion, 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:
A simple article that answers one question is easier to find and digest 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.
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. The title is like a newspaper headline. 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” tells them that this is exactly the article they’re looking for.
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.
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:
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 words. This lowers the article’s relevance across all searches except one where the user happens to use the exact words in the article title.
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 app, 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:
If they use Google, the results are even more informative:
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:
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.
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 go 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.
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:
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.
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.
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 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 Client 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].”
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.
We can split a group of simple articles among multiple authors who can work in parallel and complete the articles faster. We can 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. We can track and manage each article independently rather than trying to track individual sections within one article. We can send articles out for review as soon as they’re ready and only to the appropriate reviewers for that article.
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.
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:
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 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 then 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.
Listed below are reference materials related to the principles, standards, and guidelines for KBs and modular documentation.