Tuesday, December 07, 2010


Is it possible to create too much documentation?

Many people complain about the lack of documentation but never noodle when they have too much...

Nowadays, code is changing hands faster than one has ever planned. Drivers of this behavior range from reorganization to offshoring. Regardless, of the stimulus one needs to stop thinking that the documentation is lacking and start evangelizing the fact that too much documentation exists.

In my years of experience, I have never really suffered because of the lack of project documentation. Most IT folks are smart enough to figure out things without it. What I have suffered from is the lack of clear code regardless of documentation existing or not. Who wouldn't prefer clear/clean code and no documentation to unclear/unclean code and good documentation?

Let's face it, we often suffer not because there isn't documentation but because the existing documentation is horrific. Ask yourself, how many dollars has your organization spent on preparing documentation that was never used for anything important? Does it make sense to spend even more money in this regard?

It is important to note that my perspective on documentation is different than the masses. In the same sense I enjoy writing code, I also love writing (this blog is an example) and drawing pictures. I love talking to people and learning what their projects are all about. I am not advocating minimizing the amount of documentation created as on any given day, I just as soon write words as code. As an Agilist, I do believe in maximizing the amount of work not done.

Have you noticed that people who spend time reading documentation almost never seem to derive satisfaction and/or answers anyway? They take the document, (perhaps) read it, then come back and talk about it anyway. If you know that conversation is the end result, they why not lead with it?

Ask yourself, is the challenge really about having too much documentation or not enough documentation or is it really about having too much process or not enough process? Projects can go awry for a variety of reasons which is usually another call for comprehensive documentation. Can we acknowledge that suboptimal projects do go astray because they are wasting time and resources on the wrong things? If you spend time writing documentation, does that mean that you aren't spending time on writing working software?

Have you ever observed a project comprised of non-technical leadershipmanagement where developers are asked to document things such as coding conventions where they spend weeks debating the intracies of something that could be easily addressed by a format utility in a few seconds?

In the past, if you came in front of the Architecture Steering Commitee (ASC) and didn't have all your documentation completed, we would recommend putting your project on hold. Does it ever make sense to delay delivering business value simply because someone didn't complete all the documentation? How can IT and the business ever be aligned with this type of philosophy?

I remember all of us enterprise architect types commenting on the thickness of the design documents which seemed to have a false but otherwise positive influence on our recommendations. Of course we could never correlate the thickness of documentation with project success but it did make us feel better.

Can we acknowledge that the thickness of a document is about as reliable a guide to the state of a project/application as the number of lines of code? In other words, quantity does not equate or even correlate with quality. Likewise, the ability to write clean code doesn't necessarily correlate well with the ability to write clean documentation.

Please note that my commentary so far has attacked Architects and Developers but others in IT also are equally guilty. Think about the role of the business analyst who is charged with creating over-engineered documentation that is over-precise, over-detailed, over-long and guaranteed obsolete the day it is published. We all know that business requirements change over time. Does it make sense to attempt to keep hundreds of pages in sync or are there better ways of delivering the ultimate goal of producing high quality working software?

For the record, I believe that we should not abandon having developers write documentation. The process of writing things down forces you to make explicit things that have been implicit. You have to look at the words on paper (or on the screen) and ask yourself whether you believe that is really true. Simply asking yourself questions is a valuable exercise. The question at hand is whether others need to consume it.

Have you ever thought about the simple fact that IT is under constant pressure to deliver working software at faster paces than in the past? Everyone wishes they had more time to write clean/clear documentation, but the time to do so is never easy to find. Sooner or later you will run across someone who is unfamiliar with the activity at hand that will start poking around for documentation. They will of course find that the documentation is not up to date. Instead of thinking of this as an opportunity for you to update the documentation, maybe a little inversion is in order. The simplest solution is to state the challenge up front to the newbies and ask them to help maintain the documentation. Their perspectives as a new user is close enough to being clueless to be useful. Asking experienced people to read/review documentation is a fail, but in asking those who are clueless will allow for new insights to emerge...

<< Home
| | View blog reactions

This page is powered by Blogger. Isn't yours?