Tim Murphy's .NET Software Architecture Blog

April 2007 Entries

What Is A Document Worth

I have been working on a documentation improvement project for my current client.  This, along with a post by Jeremy Miller got me thinking again about the worth of documentation.

The client uses a predominantly waterfall methodology, but their design documentation contained very little if any detail.  The argument was the same as Jeremy's for not liking to do documentation.  It becomes out of date.

Now the big difference here is that Jeremy is talking about agile processes in which you discover your design as you go and everyone is involved in the design.  My client has standard waterfall phases and plans to hand off the design to people that may have been brought in just for build or are even outsource it. 

In this case I think detailed documentation, even if it is somewhat out of date, goes a lot further to getting the build right than having the build team constantly going back with the same questions that the design team already answered.

For maintenance I also think that having documentation that at least shows you the direction that was intended is valuable.  If you have documents that are even 80% correct can save you a lot of time rediscovering intent from the code.

Of course this approach makes process enforcement important.  None of us like to do documentation.  You need to set aside time at the end of each phase to update the documentation.

Does this mean that I am against agile approaches?  Not by any means.  I have yet to see them implemented except in a maintenance project.  I am merely saying that documentation can be a good thing and some times needs to be detailed.

Too Much Information

I was listening to .NET Rocks last week when Dan Appleman and Richard Campbell decided to start talking about the early days in computers.  I decided to have a little fun and send the show an email with what I remember of the early days of computing.


They read it during the show.  Of course it sounds funnier with Richard reading it than when I wrote it.