October 10, 2006

...Learn TDD with Codemanship

Documentation As A Side-Effect of Design

One thing that sends shivers down my spine is when managers refer to UML models as "documentation". We have a bit of a blind spot when it comes to this subject, I reckon. Certainly most teams do it because they think they ought to. Rarely does anyone ask; "Who is this documentation for, and what will they be doing with it?" Also, I've barely ever seen a team account for the time and money spent creating and maintaining documentation. Most project plans don't allow for it, and most project managers insist on it. I think there's a book out there somewhere that says we have to do it.

Interestingly, a lot of managers are less interested in design quality than they are in the documenting of design decisions. If I were a more cynical man - which, thankfully, I am - then I might think that this is because managers tend to be more concerned with covering their arses than with the actual end result. At school, when we solved mathematical equations we were encouraged to show our working. We might get the answer wrong, but if we followed the right thinking process then we'd pick up at least one mark. I suspect some managers still apply this reasoning to the design process - and software development is one big design process. If we can produce documentary evidence that shows we followed the right process, then if we still end up with the wrong design it can't be entirely our fault.

But when I try to talk to managers about actual design quality - the quality of the end product - they stick their fingers in their ears and sing "la la la, I'm not listening" (a very common management strategy for making bad things go away). When we create UML models, we might think we're doing design, but that's not how a lot of managers see it. They don't care how we do design, just as long as we leave a detailed paper trail that documents our design decisions. This is more commonly referred to as burocracy. And it is a bad thing, because it makes no material difference to the outcome.

Equally bizarre is the association many people draw between documentation and quality. I've seen a lot of organisations try to improve the quality of their code by documenting it. I've seen that work in fantasy films, where the hero creates reality by simply writing it down in a book. But I've never seen it done in real life. In real life, when I document what a piece of code does in, say, Microsoft Word, the code remains completely unchanged. Even when I screw my eyes up tight and wish really, really hard, it makes no material difference to the code whatsoever. In order to change the quality of the code, you must change the code. UML is not voodoo, despite what you may have heard.

Documentation is a side-effect of model-driven design processes. Going up to the whiteboard and doing some collaborative design adds value because we can make some key design decisions in a much cheaper and more interactive way than by writing code. If some of the models we create might be useful to help explain aspects of the system later, then it makes sense to keep them in ice somewhere for future use.
Posted 14 years, 3 months ago on October 10, 2006