The documentation “trilemma”

Most of us are familiar with the business truism “Good, fast, cheap:  pick two”.  A few years ago the documentation team I led discussed documentation quality and settled on another trio.  Documentation, we agreed should be

  • accurate
  • complete
  • accessible

If you http://www.tonysplate.com/Kitrics_Nutritional_Scale_Food_List.pdf viagra no prescription are in need, then look for the best of professionals to get started with the basics of teaching skills so that a student’s gets an understanding about base of a particular industry. This prevents several penalties web-site here viagra sale uk and late fees. Before you take up with the treatment you need to make viagra generic sale sure that you actually DO need one of the drugs, used to treat men’s erectile dysfunction problems. The exercises that I offer in both of my programs, the Erectile Mastery program cheapest viagra in australia and the Ejaculation Master program.
This isn’t quite the same dilemma (or trilemma?).  Accuracy exists independent of completeness and accessibility.  Moreover, accuracy isn’t optional; inaccurate documentation makes a product as whole less usable, and less trustworthy.

Completeness and accessibility are more of a true dilemma, though, and involve trade-offs.  The more we make documentation complete, the less accessible it becomes (more detail means more irrelevant chaff for the reader to search through trying to glean the kernel of useful information).  Excessive completeness was long the bane of users, as technical documentation provided reams of technical detail about features and options available in each software product, with little real guidance to completing whatever particular task the user had in hand at the moment.

Conversely, the more accessible we make the documentation, the less complete it may become, as we remove detail to focus on more common, important, and relevant matters.  For example, Microsoft already documents Windows, and browsers have their own documentation.  We do not need to document either of these products, as their producers already document them more effectively than we could.  Another common approach to filtering detail is the “80/20 rule”:  eighty percent of users use twenty percent of features.  So we ensure that we focus our attention on those features.  A major portion of the documentation work when designing new features is identifying that twenty percent and ensuring that we document them correctly.  A side-effect, unfortunately, is that some features are not as well documented as we, our our users would like.

One way around this problem is to implement an open documentation or community-oriented documentation approach, delivering  documentation on a wiki platform, coordinated with a support forum and blogs.   This approach helps improve accuracy by making it easier for users to report errors, and easier for employees  to correct them on the fly.  In fact, edit rights on a wiki should be open to development and tech support teams as well as the documentation team specifically so they can correct trivial errors quickly.  The search and tagging features of wiki enhance the accessibility of the documentation, allowing the documentation team to add more content.

Moreover, you can provide users with the ability to help guide you in determining the right content to provide by opening a “sandbox” on the wiki, an area where they can contribute documentation they see as needed or useful.  A sandbox hands some of the power of documentation design over to the very users of that documentation.  The documentation team can, and should, keep an eye on the content contributed to this sandbox, ensuring that it is accurate, and evaluating whether customer-contributed content should be incorporated into the official documentation.

Leave a Reply