When I do assessments, I ask for lots of project documents and data. A few years ago, I was working on an assessment for a very large system, so I asked for an architectural picture. I was surprised–this million plus LOC system had no picture at all. No wonder it was so hard for the people to plan, organize and execute their work.
I've had the opportunity to look at design documents recently. Many of them have only words. No data flow, no picture of how this piece of the system works, or how this piece of the system fits into the bigger system.
Now, I'm no artist. I've discussed my phobia about pictures before. But I've realized that if I can't draw a picture of a complex problem, I probably don't understand it well enough to solve it.
If you're implementing by feature and working with a large group, an initial cut at a design, whether it's a whiteboard discussion or a design document, might be a useful technique to help people head in a reasonable direction. But don't think words are enough. And if you're working in an Agile team, you may not need a document at all, but you will need a picture.
Draw a picture. You'll find people are able to see the design better than they can read it.
The opposite approach (settling only for pictures) is also not encouraged.
Many developers are setlling for a set of UML diagrams to express (and think of) their design. A set of diagrams, while necessary, cannot capture all of the important design issues that might be worth a discussion. Thread safety issues, behavioral contract and a bunch of other explicit assumptions and issues are all very hard to capture using the common UML notation. Sometimes, even the rationale for a certain design decision might be worth capturing for future reference.
You have to add your own notation, and probably some plain English explanations to such non-trivial issues.
One of the common misconceptions that I encounter with documentation of all kinds (requirements, design, etc.) is the lack of understanding of the real purpose of the documentation, i.e., to communicate effectively. The numbers vary in case studies, but the overall trends seem to indicate that while most people will “get it” from a picture, there are a significant number who need the textual explanation.
From my own experience, I find that using diagrams to illustrate the “big picture” coupled with supporting text that goes into the details provides the best coverage for all audiences. The ones that only want to get the “big picture” look at the diagram and the ones that need the details dig into the text.
One of the fallacies associated with the use of UML (or any other picture-only representation) is that it is a lingua franca that provides all things to all audiences, a fact that is demonstrably untrue (and for the record, I like and use UML daily). However, it seems that most shops either opt for one approach or the other based on the perception that it’s too much additional work with little return and requires a lot of work to maintain. While I can attest to the rapid pace of change in software development, in really large systems forgoing proper documentation leads to cost and schedule overruns due to things simply being missed because they were not visible.
Smaller systems that lend themselves well to agile development should still make some effort to keep things documented. There’s nothing more aggravating to all parties than getting a fair piece down the road and not remembering why that particular path was chosen. I would suggest that while tempo is important, moving too fast is just as bad as moving to slowly.