Martin Fowler is the author of UML Distilled
, which I believe is one of the few books about UML worth reading. I was reading Martin Fowler’s website last night and came across The Agile Manifesto and an article he wrote for SD Magazine. One of the topics is design documentation in which he states:
Inevitably, when discussing agile methodologies, the topic of documentation arises. Our opponents appear apoplectic at times, deriding our “lack” of documentation. It’s enough to make us scream, “the issue is not documentation—the issue is understanding!” Yes, physical documentation has heft and substance, but the real measure of success is abstract: Will the people involved gain the understanding they need? Many of us are writers, but despite our awards and book sales, we know that writing is a difficult and inefficient communication medium. We use it because we have to, but most project teams can and should use more direct communication techniques.
“Tacit knowledge cannot be transferred by getting it out of people’s heads and onto paper,” writes Nancy Dixon in Common Knowledge (Harvard Business School Press, 2000). “Tacit knowledge can be transferred by moving the people who have the knowledge around. The reason is that tacit knowledge is not only the facts but the relationships among the facts—that is, how people might combine certain facts to deal with a specific situation.” So the distinction between agile and document-centric methodologies is not one of extensive documentation versus no documentation; rather a differing concept of the blend of documentation and conversation required to elicit understanding.
This touches on one of my favorite rants, why we do design documentation. The importance of design documentation shouldn’t be minimized. I’ve found that many times people don’t really understand a problem until they can explain it in text and diagrams. But understanding the problem is the goal, not documenting the design. The format of the design document is not important. If someone has a well organized notebook and wants to pass around Xerox copies of it, that’s good enough for me. Once you start coding, the design will evolve and the documents become obsolete. It’s much like what Eisenhower had to say about battle plans: “In preparing for battle I have always found that plans are useless, but planning is indispensable.”
The attitude of documentation as goal also effects the review process. Some review processes state that everyone should come to a review with a list of issues and only issues and not solutions may be discussed. This approach stifles interaction and the creative process of the team. I have also sat through far too many document reviews that were advertised as design reviews. In these reviews people point out punctuation errors or variations from the standard document template. You can spot this kind of review because the document author starts out by saying “Does anyone have comments on page 1?”
I believe that the designer should not go through a document at all in a design review. Rather, the designer should present the design at the white-board. This facilitates discussion. The design does not appear to be cast in concrete as it does with a complete, nicely formatted document. The reviewers are more likely to offer alternative design ideas or point out problems. The review’s goal is a better understanding of the problem and a better design.
so useful that I’ve just ordered 
by the same author. Again, much of what makes well designed web pages applies to user interfaces in general.