Communicating Software Design
In a recent post, Johanna Rothman is talking about the need for pictures in design documents. Many design documents I’ve seen, however, suffer from having only UML diagrams with almost no plain English descriptions.
It’s true: a picture is worth a thousand words. But a picture cannot always tell the whole story. When it comes to software design, there are cases where a thousand words are better then a single diagram (or at least they are required as annotation to the diagram).
Trying to communicate the design of a software system or a software component using only UML diagrams is futile. A set of diagrams, while necessary, cannot capture every important design issue. Thread safety issues, behavioral contracts and a bunch of other implicit 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.
Design documents are important for capturing such abstract ideas and implicit knowledge for future development tasks. It doesn’t make a difference if you are working in an Agile team, or not. A picture alone will probably not be enough if you want your successors to have all the implicit knowledge you have today.
A design document with both pictures and verbal descriptions is essential for any maintenance task. It is especially important for future extensions of the product.
Without some sort of comprehensible description of the product’s design and structure, it is extremely hard to predict the impact of such changes on the product.
More on communicating design in the near future.
