Design Documentation

When I presented ExtremeProgramming to our group here a while back, one of the hardest points for engineers to swallow was the lack of Design Documentation.

I think you need to have some Documentation. What we've used in our projects have been sets of pictures, drawn with Visio, printed with a colour printer (colour coding subsystems makes a huge difference), showing class hierarchies and scenarios. This document gives you a starting point - we go no further than public methods. It's quite minimal, sufficient, and I think (convince me otherwise) that it's totally necessary.

-- RichardDevelyn

Does this initial design prove to be always right? How much work do you have to do to keep it up-to-date, then? Or do you just do it to get some ideas and then discard (more like the XP way)? The point of XP is that design changes, always changes, no matter how much time you invest into it, and it changes especially during coding, as coding is a great way to reveal design errors. So keeping the design documents up-to-date is a lot of work.

DocumentationIsAsDocumentationDoes. That implies you can test anything that "does" something.

The nightmare we all tremble before is GoldOwners wielding paperwork that represses flow.

The design documents are minimal enough that the work to keep them up to date is small. Every sub-system has one class diagram plus, typically, 2-3 scenario diagrams. With around 7 or 8 sub-systems to one of our applications, we're looking at 30 pages or so of Visio drawings. Changing a drawing takes minutes. -- RichardDevelyn

But refactoring a drawing can't be tested except by review.

Yup. And in this instance a review is just fine. There are plenty of places where paper documentation runs the risk of being out of step with the real world but we're happy to use it anyway. Looking around my desk I see a list of people's extension numbers, a pocket guide to Gnu Emacs commands, my work diary, a documented release procedure - all of these could be out of date, but I'm happy with them because they don't take much to fix and it's fairly obvious when they're wrong. A simple set of pictures acting as road map(s) to your application is the same (for me). -- RichardDevelyn

I have observed that DesignDocumentation can save time but only after development has entered into the MaturityPhase? of development.

Teams can successfully pursue development using AgileMethods without using design documentation as long as the SoftwareRequirementsSpecification? are complete. This method of development is successful up until the point when a feature's dependencies are all StrongConcepts.

I have observed that software goes through three phases during development with AgileMethods: (1) CreationPhase?, (2) MaturityPhase?, (3) ReleasePhase?.

During the CreationPhase?, concepts are changing, subject to massive refactoring and are fragile. They are typically iteratively evolved and created without design documentation. Protection against their incorrect development is enforced through good practice of AgileMethods such as CodeRefactoring?, CodeReview, etc. DesignDocumentation for these concepts is difficult to produce because their dependencies are (a) incomplete, (b) not even implemented, or (c) will be understood after refactoring. Any time spent on DetailedDesign? would be TimeWasted?. The various concepts are eventually hardened and become StrongConcepts when their reason for existence is agreed upon by team members and their functionallity will typically only be enhanced instead of changed.

During the MaturityPhase? of a project, most StrongConcepts already exist. The concepts may require enhancement, but they are considered StrongConcepts because of their correctness. At this point, it may be easier to create DesignDocumentation for complex features on a per-feature basis because their dependencies are not subject to massive change. There is less likelihood that the concept will have a massive replacement and as such there is less documentation that would be lost - DesignDocumentationIsExpensive?. Since there is now less of a risk of losing documentation (the concept changes and the documentation becomes invalid, therefore lost), and it is easier to produce documentation (where, why, what, how, implications, effectiveness, security, etc., are all quantifiable and correct), DesignDocumentation becomes justifiable. With a correct design (written), it becomes reasonable to delegate the implementation and the dependence upon that implementation to others.

By correct, I assume that no major or minor issue is left to chance as every implication is understood.

During the ReleasePhase?, DesignDocumentation (on a per-feature basis) is an absolute must.

I must highlight that I refer to medium-sized highly technical projects whose solution is beyond the grasp of a simple database reporting application that would be trivial to implement; is smaller than those large projects that developed by 30-50 developers for use in the military or has life critical applications.

In the scenario where you've got a small team of developers that want to build some small database application, the cost of developing the application may be more that the amount of time it takes to develop the complete solution (assuming good development practices are followed).

With a large team (or project), I expect that the process of creating correct DesignDocumentation documentation is slightly different. An example is how MessagingMiddleware? is an example of a technology where a SystemArchitect could sit down and produce DesignDocumentation that relates to how components communicate.