Monday, May 4, 2009

Documentation Dilemmas

Two areas that I have always found lacking in almost every organization that I have interacted with are metrics and documentation.

While the reasons for lack of effective metrics application in organizations are varied and include psychological mind games and politics, the reasons for poor documentation are simple. They are laziness and the misconception that “things will get along fine without proper documentation”. Truly, this is an area that senior management can influence easily; gaining a lot of return for a small amount of effort expenditure.

Detailed definitions of standards for documentation exist in abundance on the internet. Therefore, the focus of this post will not be on standards and templates for documents. Rather, the justification for proper documentation and suggestions for ease of implementation of proper documentation will be presented.

The purpose of documentation is to either provide proof or evidence of something or to provide a form of communicating information. While the first reason is generally relevant for adherence to standards (such as SOX) or to backtrack and determine causes of a problem (after the problem has occurred), it is the second reason, documentation as a form of communication, that is proactive and will assist in removing defects “before they occur”.

I, personally, have always been a scrupulous documenter; a quality, that I believe, was inculcated into me at a young age by my parents. While the habit of keeping detailed documents made me efficient at work, I was also considered a bit of an oddity for my documentation habits. When I would attempt to reason with those who preferred less documentation, the standard reply would be “But I know all that. It’s already in my head. I don’t need to put it down on paper.” While this may be true, what about those poor souls who do not have it all memorized? What about new employees of the company that do not know everything? The great thing about documentation is that it allows everyone to be on the same page quickly. It also provides a baseline from which everyone can work together. The benefits of detailed documentation are:

  • Better communication between business and IT and a properly aligned agreement of the services and functionality to be provided to the business by IT

  • Better documentation of risk which leads to better handling and management of risk

  • Improved traceability throughout the system development lifecycle which leads to a better aligned product or service with fewer defects

  • The ability to make changes quickly and without disruptions which leads to better product positioning by the business and an edge over the competition

  • Improved disaster recovery capabilities due to properly documented disaster recovery plans

  • Effective training of new employees allowing them to be productive faster

  • Errors that are avoided because of clear, well-written procedures

  • Effective gathering of metrics which can then be analyzed for potential improvement drives and improved pinpointing of problems and opportunities

  • Improved sales that result from the availability of easily referenced product information

  • Better scheduling and project management

  • Improved inter-employee communication leading to less chaos and enhanced employee morale

Therefore, the benefits of detailed documentation are numerous and ubiquitous. It is a shame that fear of a small amount of initial effort derails the documentation effort and all its benefits. It is up to senior management to enforce the proper application of documentation and not let a few tantrums by the staff hinder this important aspect of the organization. It has been my experience that once the initial hurdle of “extra” documentation has been cleared, people generally get used to it and it becomes a part of everyday life.

A technique that I have used often in the past to produce prodigious amounts of documentation has been to utilize existing documentation and simply “cut and paste” new information into the existing format. For example, once a Service Level Agreement has been created, it is easy to start with it and create another SLA for a different but related service in the same organization. This technique can be used for requirement documents, project plans, test plans and test cases. It is generally only the creation of the first document that requires significant time and effort.

Documentation is really at the heart of effectively managing anything, whether IT or any other activity. Other industries have understood and embraced quality documentation techniques and standards long ago. It is time IT adopted these techniques as well.


  1. While I am big on documentation also, I think the analysis of why documentation is not occuring is weak. For employees to document, there has to be a compelling personal payoff for a behavior change. Also, you may want to review whether you are hiring people who will write at all - many think it above them, or they are unsure what even to write. Often, getting things "documented" amounts to filling binders - how do you also ensure they will be read? Actually - who has time to read from a binder anymore? When its time to solve problems, I hope the information is not buried in a binder somewhere. Many organizations are producing shelfware, and employees quickly tire of spending energy when they see no actual value - that is, their hard work writing it down not being used. So - the rest of the problem is how to get the whole thing "closed-loop"; IT people work the craziest hours - you are asking them to add something on top of that - so you better also establish the systems that make sure contribution is rewarded and used. That final word is very important, BTW. Documentation must be quick, brief, actionable, current, findable, unambiguous, reviewed, accurate, non-conflicting.... or it may not get used; I would suggest that generally the commercially available systems do little to help this happen, and also that you will at least need to provide guidance and templates for quality content. You will need to define simple information lifecycles wherver you can, mechanisms for archiving, and more. I am working on a system to help address these issues - because I would submit it is not the employee's fault at all... And making them the scapegoat is the easy way out. Industry has done a poor job of filling this need with tools and techniques. Management is always accountable - when something is not working, you have not finished the problem solving yet.

  2. Visionary1usa,

    Thank you for your comments.
    I agree that in the end management is accountable for the success or failure of documentation at the organization and in the blog stated that documentation is an area that senior management can influence easily.
    It is up to management to ensure that the workers get the appropiate amount of time and tools to create effective documentation.
    Where the workers are at fault is when they do not produce good documentation even though management gave them the resources to do so. I have seen this happen many times.
    Also, documentation can be in soft-format and doesn't necessary have to be a binder that no one uses. Indeed, most of the doucmentation today is soft-format.
    Whether documentation gets used or not depends on:
    1) The quality and relevance of the documentation
    2) The culture of working with documentation at the organization. Even the best documentation will go un-utilized if the organization doesn't have a strong culture of documentation usage.

    Good luck with the system of documentation you are working on at your org.


    Vivek Shrivastava