The Curse of the Documentation


Good evening.  Oh, I didn’t mean to frighten you. But now that I have your attention it is time we had that conversation.  Yes, you.  Don’t bother trying to look the other way.  No, my friend, looking down at your shoes won’t work either.  We have put this off entirely too long now.  You know that I’m right.  Sure, it’s a frightful topic and I know that you’d rather be in a dentist’s chair having a root canal.  Nevertheless, the time has come to discuss…documentation.  “Only this and nothing more.

There is no escape.  Documentation is the specter of just about every BI (or IT) project.  Everyone recognizes its necessity, but nobody wants to write the dreaded stuff let alone pay for it.  Even when planned for, most documentation winds up being an afterthought at the end of the project when deadlines are short and budget depleted.  Documentation delivered under those circumstances tends to be incomplete and in many ways not useful.  I suspect that there are only six or seven human beings drawing breath on this planet who do not abhor the prospect of writing documentation.  I know one of them personally but I do not have sufficient perspective to vouch for his sanity. “Nameless here for evermore.”

Given time, budget, and inclination, what makes good documentation?  A baseline definition might be, “documentation is good if it meets the requirements of its target audience.”  But unless the requirement is to fill a bookshelf permanently with sepulchral tomes, we need to know who the target audience is as well as what its requirements are.  Typically, the target audience consists of one or more of these groups.  “Merely this and nothing more.”

  • Production Support:  Software breaks, sometimes because of code flaws and sometimes because of poor data quality.  Production support needs to understand how the solution is put together and why in order to rapidly and successfully diagnose and resolve problems.
  • Solution Administrators:  A distinct group may administer a solution, or it may be the responsibility of production support or the business users.  In any case, administrators need to understand the structure and the management of solution metadata and processes.
  • Business Users:  These are the individuals who use the solution on a daily basis.  They need to understand the business processes and how to use the interfaces.  In some cases, as noted above, the users are also the administrators.  They also need a source for understanding or remembering the business reasons for the solution design and available functionality.
  • Developers: Technology solutions routinely require adjustments and enhancements. Developers who have worked on to other projects in the interim or new personnel just coming on need solid documentation to remind them of what was coded and why.

There is nothing unfamiliar there, right?  But the question is, are there really four separate constituencies with a combination of distinct and overlapping needs, or only one constituency with integrated requirements? Granted, the business users may not be interested in the structure of the underlying data, but everyone else should be. On the other hand, the business rules that drive those data models are critical to everyone. The production support technician or developer who does not understand them is as dangerous to the enterprise as the business user who does not.  Additionally, the power user should have a place to go in order to understand the data model within a business context.  For this reason, I have been evolving toward an integrated or “ecumenical” documentation style for years.

This still begs the original question,  “What constitutes good documentation?”  What is the standard by which we judge its value?  By now, many of you are thinking, “Okay, I may not be able to articulate it, but I know it when I see it.” So what do you see when you see it?   “’Tis the wind and nothing more!”

Since we tend to remember the macabre before we remember the good, it might be easier to extrapolate ideas from poor documentation first.  For me, one of the most prevalent forms of inadequate solution documentation is the standardized template, particularly those of the fill-in-the-blanks variety delivered in a PDF file.  I absolutely understand why large IT organizations must have them. After all, you simply cannot have as many formats as you have developers and project managers.  Moreover, it is hugely advantageous to know where to go for what information irrespective of the solution.  The problem is that so many of them are byzantine monstrosities, clearly not crafted by anyone who must write or use them regularly. The most egregious examples are full of arcane acronyms and terminology resembling the artifacts of a long dead race.[1]

One of the key problems that arise from standardized documentation templates is that they breed irrelevant content.  For instance, one might have finally figured out what the terminology means only to realize that the topic is irrelevant.   Still, writing “N/A” might look like one did not think about it at all, so instead the writer will insert words even if they do not mean much.  Irrelevance creeps into non-standardized documents as well, particularly when the task of documentation has been handed to a “documentation specialist” rather than the solution architects. Such specialists are rarely close enough either to the design or the business to know what is really relevant.  Still, they must fill pages with content.  Consider the cost when the resulting document is handed to someone who was not part of the initial project.  Remember that game of “telephone” we played as children?  “Darkness there and nothing more.”

The most indefensible sin, though, is when documentation is not kept current.  Notwithstanding the value of the initial documentation, one should hope that it was at least complete and accurate.  But reflect on the potential damage to an enterprise if that document sits on the shelf for several years, not being updated with changes and fixes. If that same document were to be handed to a developer prior to a major new enhancement, the result could be a spectacular train wreck.  “Then the bird said ‘Nevermore.’”

Good documentation, then, must be none of these things.  Here are my key characteristics of good documentation.

  • Good documentation is thorough.  It articulates how a solution is put together from an architectural and structural way, provides full business and technical context, and highlights all aspects that are atypical, not intuitive, or represent risk.
  • Good documentation is business-driven.  Technology solutions exist only to satisfy some business purpose.  That purpose must be integrated into every nook and cranny of the document.  The entire audience must be able to understand why key design decisions were made and what the business impact of changes would be.
  • Good documentation is clear. Illustrations should be insightful and comprehensible. Text should be well written (meaning good grammar) and lacking in verbosity.  The overall structure of the document should be logical and should be supported by a detailed table of contents.  It should be presented in terms everyone can understand, from developer to business user.
  • Good documentation is extensible.  It should support change that occurs over time including enhancements and bug fixes.  It should articulate how and why the solution has evolved over time.
  • Good documentation is validated.  It should never be merely handed off.  The document audience should review it, discuss it, and ask questions about it.
  • Good documentation is up to date.  There is nothing more to say.

Alas, not having found it myself, I cannot lay before you the holy grail of documentation. If anyone can, I would not mind seeing it once before the grim reaper comes for me.  But I have evolved some practices over the years that make it easier to approach the spirit of the six characteristics above.

  • Go ecumenical. While I still think there are circumstances where separate technical, user, and administrator documents are appropriate, I document almost exclusively for a diverse but single audience.  The challenge with any other approach is to know exactly where to draw the line in terms of relevance.  I have demonstrated above how relevance of technical versus business versus administrative is variable from person to person. Integrated documentation provides full context.
  • Document as you go. I build time for documentation into every stage of my project estimate, and write at least the outline of each topic as I code it.  Not only does this save me time at the end, but it also helps me capture the nuances better because each topic is fresh in my mind.  It also appears to reduce the cost of documentation in the project estimate.
  • Reuse, reduce, and recycle.  I try to make every piece of documentation as reusable as possible, reducing writing time, enforcing consistency, and increasing usefulness.
  • The appendix is not vestigial.  For years I struggled with the problem of how to organize all of the business nuances that drive unusual design choices, user-defined master data, and on-demand processes in many BI projects.  I finally settled on custom appendices at the end of the document, accessed from the table of contents.  This allows me an informal structure for each topic as well as eliminates the need for a meaningful order.  I have found this to be a really good way of highlighting the business context of the solution and it has evolved into perhaps the most pan-useful part of the document.
  • Do it yourself.  Unless you have someone on your team who is really (I mean really) gifted at documenting what he/she does not really know, I recommend that those who did the work prepare the documentation.  Then if you need an editor to tighten the language and correct the grammar, bring someone in from outside the team.  High quality and relevant content is paramount.
  • Do not self-publish.  Hold a formal review with the document audience.

This is neither easy nor foolproof. I take pride in the quality of my documentation but struggle continually with the execution.  As much as I try, the first question I am asked following a project is…you guessed it…not answered in the document.  But like everyone else, I rely on documentation at all stages of a project.  I use it in early phases to understand legacy systems.  During design I might use it to assess which of the company’s two ETL platforms I will use.  Later I may need to remind someone the reason for a particular decision made twelve months earlier.  In subsequent phases, I need to remind myself of those same things.  Throughout the project lifecycle, access to high quality documentation is a success factor.  All too often, it is simply not available. “Quoth the Raven ‘Nevermore.’”

And so, my friend, this suggests that the curse is not the documentation, but rather our collective lack of discipline in writing and maintaining it.  It will never be as glamorous as writing killer code or delivering that cool dashboard.  But we need to make it possible for those colleagues who come after us to find their way in the darkness.  We need to make it possible for those who use, administer, and improve the solution to do so intelligently.  We need to begin making our system documentation more a reflection of the business value of the solution itself.  After all, it is better to light a candle than to curse the documentation.

How many times have you been stopped or slowed for lack of documentation? What tips and techniques do you have for preparing quality documentation?

[1] In order to comprehend the full horror, I heartily recommend The Shadow Out of Time by H.P. Lovecraft.

5 thoughts on “The Curse of the Documentation

  1. andytilley says:

    One one place I’ve ever worked had great documentation. It was part of the culture. This company was a bank and I was an assembler programmer – that’s how long ago that was. Nowadays I largely ignore any and all documentation – out of date drivel has led me down the wrong path too many times to trust it.

    • bimuse says:

      I heartily agree that good documentation is rare, and that up-to-date documentation is even more rare. I also agree that documentation does not replace first rate analysis skills. Nevertheless, I have been saved a number of times by a document that shed light on something nobody else could explain. Thanks, Andy.

  2. Jocelyn Hoopes says:

    So this explains why the major software provider for most NGO cancer surveillance operations has no, and I mean no, documentation for its product. When asked for some they wanted me to sign a confidentiality agreement for what was basically a data dictionary. In the absence, or maybe driving it, there are at least three standard setters all responsible for different parts of the record with the software provider deferring to them for an algorithm that drives cancer staging and treatment with no documentation available to the user. This is driving THE cancer treatment that goes to quality of life, and even more directly, life and death. Thus a major amount of time is spent pre-profession in learning of whom to ask the right question.

  3. Antony says:

    When someone writs ann post he/she maintains the thought of
    a user in his/her brain that how a user can understand it. Therefore that’s why this piece of writing is outstdanding.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s