Two “big” words in today’s documentation are Documentation Portals and Knowledge Bases. For the first time in decades, it really does seem that we are seeing the end of PDF as a viable alternative for online applications (or any documentation that doesn’t involve some element of hardware).
With all these tools and formats, how do we decide what goes where? The simplistic answer is that we have to go, as always, according to the needs of our users. Therefore, we need to put information where we would expect them to look (and not necessarily where we think it belongs).
One key rule that goes above all is the concept of interlinking our documentation so that if we are wrong, the reader will find, at very least, a reasonable way of reaching our information.
So, where DO readers expect to find information?
Documentation Portals are typically understood as the “catch all” place. It’s the default link a user will click when unsure where else to look.
One problem when searching for excellent examples of documentation (both portals and KBs) is that the source is often biased and only wants to present amazing examples of companies that use their platform. arise. Here are some basic conclusions:
Basic Rules for Both Portals and KBs
- Current/Accurate: Successful documentation portals are maintained and updated regularly. If the company maintains several versions, access is available to documentation for all versions in a clear way.
- Branding: Visitors should know immediately where they have landed when they click a link. They shouldn’t have to remember what company or what product they are seeking. Effective documentation portals have the corporate look and feel and branding users would expect to see.
- Responsive HTML: If your help isn’t mobile-friendly, you might want to consider just taking it down. Seriously. In this day and age, all sites must be responsive.
- Clear, Concise, Consistent: An old rule that lives on. Navigation options and content must be intuitive and clear. Writing must be concise and consistent.
About Documentation Portals
In many ways, the most important page of the Documentation Portal is the front page. Elements it must have include:
- Prominent search option: users don’t like tables of contents. They want to search and find what they want quickly.
- Category “buttons” are helpful. Users might want to see a buttons based on products or versions, but also types. For example, documentation specifically for Developers (or Advanced Users) is helpful. Also, by type. If you have video tutorials, these should be listed in a separate section. This allows users to decide based not only by topic but also by format.
- Minimalistic design is best: On this main page, a lot of text confuses and delays users from getting to the information they want.
As for content – links to all your documentation should be located in some way from the main page of the documentation portal including:
- standard documentation
- developer documentation
- video tutorials
- technical support
At its core, the Documentation Portal is intended to provide as much information as possible to answer the primary question, “How do I…?”
About Knowledge Bases
Knowledge Bases are many things to many companies. For some, the Knowledge Base IS their documentation. It often looks like the standard online help and barely differs in content. For other companies, the definition is closer to what one might expect – a collection of knowledge. Or, more accurately, THE collective knowledge of the company’s experts.
A true knowledge base offers the “extra” information you might not expect in the standard minimalistic documentation we see today. A user guide/online help will tell you HOW to accomplish the necessary tasks. It should, ideally, also provide you with the basic “why”.
Basically, a knowledge base should take the reader deeper into the “why”, provide alternative “hows” and in general, offer an expanded view of the product. Some companies maintain two KBs – an internal one and an external one.
When maintained properly, the internal KB is a huge resource and will lessen the “brain drain” effect that occurs regularly when high-level and/or long time employees leave.
Avoiding Brain Drain
For one client, the configuration file required for every new customer installation is a vast and nearly impossible file to manage. Here, one man in the company holds the key in his brain. And, when the company finally decided to document a portion of the configuration file, the extent of this man’s knowledge became evident.
In truth, the company only documented the “configurable” portions – those parts that the customer was expected to customize. Even in those few sections, there were many instances of code terminology that had, over time, shifted meaning. Sadly, the code name said one thing; the functionality did something entirely different. Ultimately, maintaining an internal KB is invaluable and yet many companies don’t invest in this.
As early as possible in the documentation creation process, you need to create definitions. What documents will you create? What content will you put in each? Who will maintain these documents? Who will check the accuracy of the information there?
The sooner you begin, the better the outcome will be.