Technovangelism

Think back to all of the documentation you have ever produced for a single project. Include everything from meeting minutes, requirements and design documents, lists of assumptions and anything that is considered “required” for your project. How many times have any of those pieces of documentation ever been read? If it’s anything like the teams I have been on recently, it is close to zero. Certain kinds get read more often than others, but the collective average is quite low.

What is the point of writing something that is never going to be read? Don’t pay any attention to the number of readers of this blog. Developers are constantly told not to waste time on features that will not provide value for the customer, but we are sometimes forced to write documentation that can provide even less value. Does my customer care that I took meticulous meeting minutes? Do they even care that I made a list of assumptions that should help the next developer who takes over my code? Probably not. They do care that you deliver on what you promise and that development continues to progress well regardless of who is doing the actual coding. So can it be said that documentation provides real value to a customer?

Not only does documentation often provide little to no value, but it gets out of date quickly. If you are one of the heavy producers, go back and read something that was written only a month ago. Not only will this probably be the first time anyone has read it since it was written, but it will not properly describe what your project has become. Any specs or details that were once important to the project will be meaningless at this point. Projects evolve so quickly it is nearly impossible for a document even one month old to hold much weight.

Worthless documentation can be found everywhere, not just in .doc files. Here is a snippet of code (why yes, it is VB) I found, complete with “documentation.” This comment might have been useful in the past, perhaps if the methods had different names or there were a few more lines in between them, but at this point that comment is worthless and was waste of time to write.

  ' Start the module into rotation and restart the timer
  module.StartRotation()
  m_ResetTimer.Start()

Final thoughts: Do I hate documentation? Of course not. But I would rather only write something that is going to read by someone other than me.