Are You Maximizing Your Enterprise Documentation Potential?


Everyone knows you’re supposed to read manuals that accompany products and services you buy, but of course, often we just blaze ahead, unpack, and put whatever object we just bought to immediate use based on our intuition of how it should be used. That works sometimes (a new pot or pan), is less successful other times (a new outdoor tent), and outright fails other times (a new BBQ from a kit). But even in that case of a relatively simple object, like a new kitchen pan, you can glean new information from the accompanying documentation. In my case, last week I bought a wok, read through the pamphlet and found out you are actually supposed to preheat the wok to the temperature you want to cook at before ever adding butter or oil. Who knew?

With software, the payoff from reading the documentation can be substantial. While we all appreciate a user interface to be intuitive as possible, even a basically intuitive device like the modern smart phone has “secrets” that are unlocked by using the documentation, both the vendor’s official documentation and the other ancillary unofficial documentation we can find on the Internet in the form of user reviews, tips or demonstration videos. I’m always amazed by and appreciate the number of people willing to post and share solutions on the Internet. Being a technical writer, I have something of a reputation among my colleagues as being a “technical” technical writer. I’m often asked where I learned this or that technology. More often than not, the answer is by reading the official documentation and using an Internet search engine to find the unofficial documentation that fills any gaps.
How can you encourage that official documentation plus additional non-vendor documentation model with your enterprise software? One challenge is that generally you probably don’t want your proprietary use of a product out on the Internet. That means everything I’m suggesting here is for your company intranet.

Key steps to maximizing your enterprise documentation:

  • The obvious one – make sure you have the official documentation from your vendor installed and updated at all times. Don’t frustrate your users with an incomplete help install that results in broken links from the application.
  • Leverage a mechanism to post your employee-generated tips and how-to articles alongside and/or accessible from the vendor documentation. Within an Epicor help installation, this is simple. Any .html file you add to the help folders (or add to a new folder you create at the same level) will automatically be indexed and appear in search results from the help search. Epicor also has other mechanisms to integrate custom additions to help such as the annotations feature that allows extended comments (which could be links to URLs) to be added to help topics.
  • Guide collaboration software like Microsoft SharePoint to create searchable forums, document repositories, and video libraries to host your supplemental material.

If you take these steps, your employees can help each other even when they are not in the office. A set of self-generated documentation that supplements vendor documentation is not immune to the demands of official documentation, such as what version does it apply to, spelling/grammar errors and technical accuracy. Depending on your tolerance for those items you can implement review boards and/or individuals who supervise documentation additions. I’m personally on the side of more documentation with less oversight than making a process in which few are motivated to participate. Taking small steps such as making your own documentation templates (that includes information such as version) goes a long way in making useful supplementary documentation.

If you set up an infrastructure where supplementary documentation additions are simple and accessible from vendor documentation, use common templates and have a searchable interface, the value of your enterprise documentation can really increase overall.

Posted by Charlie Lloyd, Senior Manager, Epicor University


Share on...