Agile and Incremental Design: Part V

How should we document design

So how do these conversations get recorded? We need something that is lightweight, easy to use, collaborative and already available. Here we can reach out to the A3 approach used within other lean approaches. One resource for A3 thinking provides a simple description and approach to this technique. But this should be treated as a starting point only.

We had already discussed the concept of the adjustable level of ceremony. This will identify the amount of documentation that is valuable and required, dependent upon your needs and the regulatory regime in which you are working in. There is no universally correct answer to the documentation which is deemed to be valuable, and we do not write documentation that has no value. But if it has value, then we must write it.

You will notice I am saying that an agile team will produce documentation. Agile does not mean that documentation is seen as waste and therefore it is not done. But we do have the right to question why a document is being written, for whom and to what value. If the answer is that the particular document is valuable and an audience for it is identified, then as professionals we write it, and we write it well.

Of course the definition of what well means is important. Traditional measures such as weight and a preamble that takes 12 pages are not really helpful. In many cases a design document is needed to show a trail of decisions and to contain the model of the implementation. This model and the audit trail are incrementally built. Story by story and feature by feature. It is most useful if it is searchable, so a printed version is less useful than the digital version.

The recommendation in this case is to create a framework that reflects the structure you are using. for example a SAFe product would have a structure that looked like this.

I have used the SAFe terminology here to describe the structure. If you don’t use SAFe, apply your own structure. The principle is the same.

For the sake of discussion let’s assume we need documentation that results from our level of ceremony being medium to medium high. Your needs may be different, discuss.

Generally the idea is to keep the size of this documentation small, hence the name A3. The A3 document will fit into the documentation framework created at the beginning, which will grow story by story. It is recommended that each story has a lead team member who ensures that the A3 for their story is maintained and completed as part of the definition of done. The A3 can contain such information as:

1. All decisions made and by whom

2. Diagrams as deemed useful, or updates to existing documents

3. Acceptance criteria with test data

4. Tests used within this story development

5. Identified dependencies and interfaces

6. Story ID in the Agile Management system (Allows tracking to tasks)

This A3 can be audited and will provide a high level of assurance that software creation is being governed. It should be noted that the A3 principles ensure conversations take place and that the key points are recorded. These conversations are about the implementation of a feature, a story or anything that is deemed valuable by the team.. A quality audit will be able to see a trace of all decisions made, which provides a very disciplined way of working.