As a programmer, technical writer, and general techie, I’ve spent a good chunk of my time scouring the Internet for solutions when technical problems arise. And when a problem is really obscure, I’ve found that you’re usually at the mercy of three things: the resources available on the Internet, the quality of your search engine, and the ability of others to write clear and detailed answers. Over the last few years I’ve helped a number of organizations optimize their knowledge bases and write articles to address technical issues, so I’ve seen first hand, the importance of identifying and clearly describing subtle yet very important technical details. In this article, I’ll share a few tips on how to approach your technical knowledge base articles, which could very well be someone’s last hope for solving a technical problem.
When approaching an article it’s good to put yourself in the mindset of potential readers. Chances are they are arriving at your article under difficult circumstances, such while trying to solve a rare IT problem that is blocking other users, and they may have exhausted all other resources in trying to find a solution.
The most important part of your article is obviously the solution. It needs to get to the crux of the issue fast, and more importantly, the steps to resolve it. But in order to be of use, readers need to be able to find your article.
So start with good search engine optimization (SEO), and make sure you know how to use your content system’s keyword and tagging features. Be sure to tag the article with every relevant keyword possible, and once the article is indexed, practice some searches using some common keywords to see how easy the article is to find.
In the article itself, start by explaining the problem that is being solved, along with the possible causes, symptoms, and operating conditions/environments. This will help the reader qualify early on whether your article is truly related to their problem, or if they should stop and look elsewhere.
Once you start getting in to the solution, ensure that you keep your article as simple and concise as possible. Chances are a reader will be jumping between the article and whatever software/hardware they are dealing with, so make it easy for their eyes to find the content by avoiding walls and walls of text.
The best way to accomplish this is with lots of screen shots and/or well-formatted and well-spaced code samples, depending on the situation. If you are using screen shots, be sure that they are clear, and that they highlight the important bits so that the user can immediately see what needs to be clicked on or entered. If the screen shots show text to be entered, provide that text in the article as well so the reader can copy and paste it. Likewise for code/script samples, use formatting like bold, italics, and coloring, to highlight what the reader needs to add or change to solve their problem.
Another useful tool is to enable commenting. This will allow other users to contribute their experiences and verify if the steps worked for them. They can also clarify and add additional steps that they may have faced under slightly different conditions or environments. Likewise, it provides you with the ability to add updated information as the problem is resolved, when new versions come out, or when your user interface changes.
Commenting also shows readers that your organization is proactively involved in helping people find solutions and encouraging conversations, so it inherently makes for good PR, not to mention that it helps contribute to your article’s SEO.
Another tip when engaging readers is to avoid asking the obvious when your solution doesn’t work for someone. This includes questions like whether their power cable is plugged in, their drivers are up to date, or their Internet is working. Likewise, asking for a Windows log dump or the model numbers of components in their home‑made PC, seldom provides any worthwhile clues and makes your support team appear as if they are working off of a script.
Instead, focus on getting to the heart of the issue. Use your in-depth knowledge and internal subject matter experts to understand the important aspects of the problem, and then respond with really detailed questions/suggestions that get to the heart of the issue.
Lastly, never leave the article hanging. If unanswered questions have emerged by contributors, there is nothing more frustrating than a conversation that ends with someone asking if anyone will be responding with an answer.
Hopefully this article has been useful. Keep these tips in mind as you build your knowledge base articles and it will quickly become a go-to resource, especially for those with technical problems who need one last hope at solving them!