The Documentation Controversy

I know that many in the software field are averse to producing documentation. Some are willing to allow that there is more than one kind of documentation: useful documentation, and then blah blah blah documentation. Others seem to condemn the idea almost completely. I can understand that many people have been burned by an expectation to produce x amount of design specification documentation, or y number of test cases by some arbitrary date. This would be a good cause for aversion, particularly if no one actually checks the documents to ensure that they contain useful information. However, I have to wonder how much of this is blaming the tool for the faults of the tool users and/or the project environment.

While poor documentation can admittedly be harmful by providing an excuse for avoiding real work (”I gave you the requirements. What more do you want?”), good documentation can be worth its weight in gold. As a visual person, I am biased towards models. I am even more biased towards the fruitful conversations that if have often seen follow the introduction of almost any kind of picture of a system, whether static, such as a data model, or dynamic, such as a use case diagram or other process model. I love seeing the understanding that dawns as a diagram is revised and honed to represent some portion or aspect of the system. Hearing someone say “I hadn’t thought of that. What if we do this, will that work?” tells me that the design will be just that much better for the sake of the discussion and the picture.

I have also begun to notice another impact of documentation when there are trust issues in the team or organization:
- it gives others something concrete to look at and evaluate,
- allows them to see what I am doing without having to expose themselves first, and
- gives them a way to improve my understanding.

When they see that I make changes as a result of their comments, they also have the chance to understand that I am listening and respecting their input. If they aren’t forthcoming with comments, I can use it as an excuse to ask them questions. I can say: “I appreciate you taking the time to help me with this. I really need to get this clear so that I don’t do anything that will cause problems for you when we get to testing.” It not only helps to create a bridge, it also strengthens it by creating a foundation for trust.

For me, the bottom line is that the the idea of documentation is not inherently flawed. Without putting something in writing, some conflicts will continue to occur over and over again since no one can “prove” what was agreed to. When I have a chance to gain so much from using documentation effectively, I will just have to cope with the skeptics who have been burned before and hope that I can show them that documentation can have its place.