The Value of Design Documentation

Recently I asked students to tell me what kinds of requirements they start with and what (if any) design documents do they produce.Several students said that they produced documentation just because it was part of their development process. As a consequence, they felt that the documents were rarely read, were hard to keep up to date with the real code, and were expensive to generate. I know that everyone isn’t free to change their process…but if something is expensive to do and doesn’t add value, especially in this economic climate: look for a better, less expensive alternative.

My advice is to keep the precision at a low enough level that you don’t have to keep updating it with every small change. Last year I helped one client develop a 2 page high-level view of the architecture for IT applications. On the first page was a component diagram. On the back was a high-level statement of each components’ responsibilities. While during development they produced other docs, these high-level overviews were intended to orient people who were going to maintain these applications. They were pleased when this high-level view was well-received by those developers.

Simply because a tool lets you reverse-engineer an implementation into detailed class or sequence diagrams doesn’t mean you should create lots of implementation-level diagrams. On another project where we used TogetherJ, we pruned sequence diagrams (to omit detail) so that business analysts could understand the basic flow w/o having to know everything. These edited diagrams didn’t end up in any permanent design document. Instead they helped explain our working prototype.

To be effective design documents have to communicate valued information to its intended audience. So if you find yourself creating documents that aren’t useful…well, think about suggesting cost cutting and process improvement ideas to your team and management. This is the right economic climate to suggest such positive changes.

2 thoughts on “The Value of Design Documentation

  1. A problem I've frequently encountered is that design documentation often gets confused with system documentation.

    Your design is an input to the development process. It helps you think through and communicate your intentions.

    System documentation is an output from the development process. It should describe your application (or architecture, etc) in sufficient detail to orient and guide those who encounter it later.

    The compulsion to keep the design up to date often results from an expectation that the design should document what you built, rather than what you *intended* to build.

    Moreover, using the design documentation as system documentation serves even more poorly when enhancing an application. After multiple updates, understanding the system requires reading (and mentally layering) multiple 'design' documents. A better approach is to instead update the system documentation (perhaps on a wiki!) as part of each delivery.

  2. You make a good distinction between system documentation and design documentation. System documentation should be guide for those who follow on. It can (and should) include rationale, restrictions, notes, and general high-level orientation to the system but if it is overly precise it will never match the system's implementation.

    A wiki that can (and will be refreshed) is a good tool for this. But even with the ease of a wiki, I wonder how many keep system documentation up to date. It is just a discipline that has to become part of what you value (and part of the rhythm of your work).

Leave a Reply

Your email address will not be published.