Fear of Design Documentation

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.

Published by


Dave Slusher is a blogger, podcaster, computer programmer, author, science fiction fan and father. Member of the Podcast Hall of Fame class of 2022.

One thought on “Fear of Design Documentation”

  1. Having written code since 1965 for everything from mainframes you can party in the middle of, to microprocessors you can lose in your carpet, I can say with some authority that you’ll never get good code without a good design. First design the system, then implement it. If you don’t understand it well enough to document it, you don’t understand it well enough to implement it. Doing the design is the fun part – coding is just the scut work you have to do to see it work. A good code generator will do that, but it can’t do the design.

Comments are closed.