Communications from DMN

One great, and often overlooked, sources of user information is a corporate knowledge base (often shortened to KB). Whether used internally or externally, the KB combines user-generated (or, at least, user suggested) documentation with more technical material. But don’t think that the content in a KB is for techies only — it can, and should, cater to users of all skill levels.

Not surprisingly, technical communicators are well-placed to develop KB articles. We’ve got (or should have) the product knowledge, as well as access to subject matter experts. Not to mention our writing, interviewing, and research abilities.

And from the standpoint of professional development, writing KB articles is useful. They teach you how to write tightly and maintain a narrow focus. That’s useful not only in writing documentation, but also if you want to branch out into writing articles. On top of that, you’ll probably have to learn how to use the knowledge base software that your company has; you never know when that will come in handy down the road.

Structure of a KB article

Most KB articles will focus on how to solve a single problem. They’ll usually contain procedures. I generally structure a KB article like this:

• Use the opening paragraph or two to frame the problem.
• Explain the solution or workaround to the problem using a procedure and, if necessary, screen captures or even a short screencast.
• Point to other resources, such as other KB articles or information on external sites.

The company that you’re working for or with may have its own KB article format or template.

As I mentioned, most KB articles will follow the pattern above or something similar to it. In some cases, KB articles are informational rather than procedural. They’ll discuss aspects of a product that aren’t covered in the documentation, or they’ll point out features that aren’t available yet.

Getting ideas

In an interview, Harlan Ellison joked about where he gets ideas for his stories: “There’s a swell Idea Service in Schenectady; and every week I send ‘em twenty-five bucks; and every week they send me a fresh six-pack of ideas.” But when it comes to generating ideas for knowledge base articles you’re on your own. Well, maybe not.

You might be assigned a topic — for example, ensuring that an application is listening its assigned port. Or, you might come up with an idea based on a gap in your documentation. Another topic might be a revised list of versions of the operating systems and supplementary software which and application works with. Take a few minutes to think about it, and you’ll be surprised at what comes to mind.

At a couple of companies with which I’ve worked, I found two very good sources of information for articles. The first one was support cases. The support team generally deals with more than a few interesting problems from users, ones which they, development, and you probably never considered. As I often say, the folks using what we document are doing things with it that we’ve never imagined. And, as a result, running into problems or limitations. A good support team will keep track of how it solved a problem, and you can use that (along with information you glean from talking with them) to create a solid article.

Another source is the documentation. Not what’s in there already, but information that didn’t make it into the final documentation. At one company I worked with, my manager and I decided that a lengthy appendix on operating system performance counters really didn’t add anything to the manual. So, we moved it out of FrameMaker, broke it up into several articles, and moved it to the customer KB. Those articles still get quite a few hits, I’m told.

Working with SMEs

Writing KB articles is a lot like writing documentation. You can’t do it alone. You need to talk with SMEs — developers or support personnel — to get their input and insights. They’ll have information that you need, and might even have a clever or unique way to solve problem or perform a task. All of this information can help users do a job faster or more efficiently.

If you can, get read access to your company’s support case database. There might be an actual database. Some companies, for example, track support cases in Salesforce.com or in tools like BugZilla or Remedy (I know those aren’t true support tools; just another case of adapting software to your needs). The support team might also maintain a wiki. Ask around.

But remember to involve one or more humans. They can definitely help you clear up any questions that you have, or point you to additional sources of information.

Writing KB articles can be interesting. It can be challeging. It can also be rewarding. If nothing else, writing for your company’s knowledge base will keep your skills sharp.