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 f 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.

Sustainable Design

In my most recent IEEE Column, Creating Sustainable Designs, I explore what it means to create software that can be maintained without too many growing pains. I have been intrigued by Christopher Alexander's writings, particularly the first two volumes of the Nature of Order where he explains the properties of designed (or architected) things which have life and processes for creating life.

It is just as important to look at process of creating good software as it is to consider what properties make software habitable for those who have to maintain it and keep it alive. While I appreciate process (and I think the agile community has given us a lot to consider) I am more keenly interested in exploring what makes complex software "living".

Alexander identifies these properties (or qualities) of living things: levels of scale, strong centers, boundaries, alternating repetition, positive space, good shape, local symmetries, deep interlock and ambiguity, contrast, gradients, roughness, echoes, the void, simplicity and inner calm, and non separateness.

It can be easy picking to draw certain connections between certain "good" software design properties and Alexander's list. For example, good shape, as others have pointed out can be a matter even as simple as properly indented a method. Or it can be more profound than that--leading you to break up a method into substeps and invoke helper methods, just to keep every step at a similar level of abstraction. I'm only giving you a taste to see whether you are interested in exploring these ideas further.

If you are,  read my column, and also take a look at the C++ Report article by Jim Coplien on Space: The Final Frontier, which introduces Alexander's notion of centers and how they relate to software structure, and peruse several very good blog entries by Regis Medina.

And if you are interested in exploring these ideas further, perhaps by taking a deep look into working code or frameworks or software that you consider to be particularly alive (or not)... let me know. I am considering finding a venue where software developers and designers and philosophers could concretely explore Alexander's properties more thoroughly. I am not just satisfied to make those simple, easy connections and call it good. I want to challenge our best designs and see whether Alexander's properties really do apply (or if we have some other properties that are more relevant).