LumiCode and Agile

by Roger Bruvold

Clarity and understanding of a software design are important to the development and maintenance of software. Good diagrams of your software's central structure elements can provide clarity, but the production of these documents is a burden.

The leanness of the Agile process cannot afford burdens, so documentation can get squeezed out, along with the value it creates. Because LumiCode produces documents with little effort, the benefits of good, accurate documents can be available, even in a lean process.

How documentation earned its bad name

At some organizations I've worked for, "design" was synonymous with "design document". "Is the design done yet?" really meant "Is there a design document yet?". Early efforts would go into producing a thick tome, complete with contents, indexes, signoffs, and appendixes. Often there was little that could be called "design" in these documents--only repetitive, mind numbing detail that was seldom referenced later.

Documentation can present these problems:

1. Deflection of purpose

   The purpose of a software development organization is to develop software. Design, coding, documentation, and testing all contribute to that purpose. But too often documents become the purpose. This is because they are visible and accessible to those who cannot understand the other things.

   The development group can become document centric, valuing long formal documents above all, and promoting those that produce them.

2. Resource sinkhole

   All software projects have limited resources, so everything you do is done instead of doing something else. Time spent documenting cannot be spent prototyping, designing, coding, or testing. Ironically, it's often the design that suffers most from the cost of doing the design document. Time better spent drawing arrows on a white board and simply thinking is spent aligning images in a document.

3. Concrete overshoes

   When design documents are created in the beginning of a project, they are done with very little insight and understanding. When better design concepts emerge later, so much has been invested in documentation that it's hard to change direction. But the cost of a poor design is the greatest of all costs.

Documentation in Agile

So there is a good reason to try to put documentation in its place--a very small place--and that's what Agile has done.

Yet it's hard to dispute the value of a good drawing of the class hierarchy to a newcomer to the group. When trying to find a good place to fix an error or add a feature, I often scribble out a call diagram on a sheet of paper. Documentation does have value; the question is whether that value exceeds the cost of production.

I propose that, as Agile developers, we embrace documentation, but on our own terms. Produce documents, but only when the benefit justifies the cost. And by making the cost low, better documentation becomes justified.

Fitting LumiCode into an Agile process

Agile developers know that a large projects need to be broken into small pieces that are modeled, coded, tested and released a regular intervals.

For each small piece:

1. Model using the simplest tools possible. For a good book on Agile modeling, I recommend "Agile Modeling, by Scott Ambler".

2. Code and build.

3. Use LumiCode to create diagrams and reports directly from the code. Focus on concepts, not details, because an add-hoc diagram can be produced at any time to show a detail.

Because the LumiCode step is so quick, it won't weigh down your process. Yet you will have good, accurate diagrams to refer to when they are most valuable.