Documentation: The Wrong Question

Some years ago a client asked me to review an object model and offered to send documentation in advance. The package arrived and hit my doorstep with a heavy thud: a full inch and a half of CASE-tool printouts. Every class, attribute, and operation was defined at length. The Contract class was described as "a contract between many parties"; its dateSigned attribute as "the date the contract was signed." By the end I knew what everything was, but very little about what the system was supposed to do.

That experience is disappointingly common. The usual culprit is a documentation culture that asks an unhelpful question: "Have we documented everything?" It's also encouraged by CASE tools with their dictionary-like approach of generating an entry for every class, attribute, and operation, and a diagram for every use case.

"Have we documented everything?" is the wrong question to ask. Answering yes means giving equal weight to every detail. In a complex system, that buries the important parts under everything else. Every system has key aspects that, once understood, smooth a newcomer's path. The skill lies in spotting them and explaining them crisply.

Say Less, But Better

Documentation exists to communicate, and communication demands brevity. Only then will people read it and only then will you keep it current. There are projects where changing a class name takes longer because of documentation than because of code. When documentation becomes the bottleneck, throw at least half of it away.

What to keep is a professional judgement. Here's a workable approach for a system of any reasonable size:

  • Start with a diagram that shows your packages and their dependencies. Minimize those dependencies; coupling hidden between packages will hurt you more than coupling inside them.
  • For each package, write a short document centered on narrative text: what the package does and how it does it. Then illustrate with a class diagram showing only the key classes; for those classes show only the important attributes and operations. Show interface rather than implementation details.
  • For each important collaboration within a package, include an interaction diagram. If a class has distinctive lifecycle behavior, a state diagram helps.
  • To show cross-package collaborations, pick the most important use cases and document each with an interaction diagram and narrative. You don't have to draw an interaction diagram for every use case, but if you can keep them current, it's fine. Even then, highlight fewer than a dozen that everyone must understand.

As a guideline, a package document should be small enough that you don't dread maintaining it, ideally no more than a dozen pages.

Tools Do Not Equal Communication

Tools don't guarantee clear exchange. One project I know used a multi-user CASE tool that every developer could access. But in reality, few did; fewer understood the models. The architect gave up on it and took over a wall at the office, posting colored object diagrams of about six key system collaborations. Not every developer now understands the entire design, but they can all see the critical pieces.

The disciplines of writing a short article and effective design documentation are the same. If you pass every detail on to the reader, you've forced them to do your job of sorting signal from noise. Selecting what matters is the most important act of communication, and it is a duty that belongs to the designer alone.