Once upon a time I worked in a place that required design documents before any code was written. I won’t go into all of the pros and cons of that particular practice here. You have probably heard them all by now. What I want to do is describe an agile alternative that I offer to teams, based on personal experience as a team member.
A design document has several intended purposes. Traditionally these include:
- to focus discussion on alternative designs
- to guide the implementing the product during the coding phase
- to describe the system as a basis for maintenance and future enhancements
My experience and the experience of many others that I encounter is that traditional design documents are not very useful for the second two purposes in the list. The main reason, of course, is that finished systems rarely match their initial designs. I often ask if anyone goes back and updates the design document after changes are made. A few stalwart individuals have claimed to, but most admit to not having the time or interest to do so.
I have also seen cases where design documents were not much help for the first of these purposes. In those cases, a “design review” was a meeting of busy developers who flipped through the document a few minutes earlier and picked out places to mark for criticism, no one giving the big picture a fair study.
A typical agile project avoids a big up-front design and therefore does not write such a document. An initial design is sketched out on the white board and the real design is allowed to evolve as user stories are implemented. For large, multi-team projects, there may be a bit more formal architectural planning at first and a small document may result.
The agile practice of evolutionary or emergent design substitutes for the first two purposes listed above. What about that third purpose? Does your project need a document that will help with future work on the product? If so, how do we create it? Is it another user story? Does it get prioritized along with other stories?
Three teams I worked on made up a practice to cover the third purpose. We called it the “As-Built Design Document”. It was based on these ideas:
- a prose description of the product is only useful if it is accurate
- the description has a better chance of being accurate if it is written after the product is built
- it is easier and safer to write such a document incrementally along with creation of the product because you never know if there will be time when all the other work is completed
Our practice was to allocate a standard overhead task to each sprint for producing an as-built document. We used a snap-shot model, creating a document for each sprint. Some teams use a cumulative model, revising and growing a single document with each sprint.
We would start on the as-built a couple of days before the demo, using a revision cycle of passing it from team member to team member. We usually ended up with a few-page document that covered the following:
- The theme of the sprint
- A short description of the stories that were implemented
- Members of the team for that sprint
- A description (ERD or text) of any changes to the data model
- A description or diagram of any architectural changes
- A discussion of any design decisions that we thought would be of interest to anyone coming into the project later
We also included the following as seemed appropriate:
- A list of any other work products produced (e.g. user help, security docs)
- Test counts and coverage measures
- Changes to the UI
- Changes to the deployment scripts
- Changes to the team work process, possibly resulting from the prior sprints retrospective
We found this as-built document to be useful for additional purposes:
- Along with our task cards, it helped us plan the demo by reminding us of what work we completed
- We handed it out at the demo as a written reminder to all stakeholders of what we had accomplished
- We used it as a ramp-up aid for new team members added in later sprints
- It was an historical record in a few cases where new design changes brought up previous discussions
- The stack of snapshots were sufficient for later maintenance and enhancement, at least as long as I was involved with the projects.
- currently coach teams in high-governance environments where there is a heavy process framework that likes to have written artifacts. The as-built can serve an additional purpose of feeding the compliance monster.
I introduce the concept of an “As-Built Design Document” in all of my team training sessions as an optional practice. It does not take much time and is a good vehicle for solidifying much of the knowledge gained during each sprint.
