Fear of Design Documentation | Evil Genius Chronicles

Fear of Design Documentation

January 28 2004 | 1 min read

The preachers at Hacknot have gotten this weary soul excited with their recent post about why developers hate design documents. They address the fallacies of the common arguments (every one of which I have also heard), and have a challenge to the agile programming community:

To the XPers who promote such fallacies, I would ask this ? if you believe you can write code in such a way that the cost of change becomes negligible, why can?t you employ those same techniques to write design documentation with the same properties? A design document does not demand the same accuracy or contain the same complexity as source code; so why can?t we just refactor a design document with the same ease with which we refactor our code? This inconsistency points to "the code is the design" argument as a failed attempt to rationalize personal preference. Twiddling with the code is fun, twiddling with diagrams is not (apparently).

They make a good case for the resistance to documenting the design or even having a design as boiling down to cover for the true cause: working with design docs isn't as much fun as hacking code. Never mind that having a good doc makes doing the code more fun, less work and a better shot at being correct, most people aren't willing to do non-fun work up front, even if it increases their fun later.