Agile Architecture and Documentation

Agile and documentation? What gives?

First things first. Documentation is not something that is prohibited by the Agile Manifesto. Working software is definitely preferred over "comprehensive documentation" but there can also be some value in documentation.

The first question is why would we want to document anything if we have a working software. I think there are several stakeholders like project newcomers, maintainers, etc., who will be interested in something that will let them get up to speed and provide them an overview of what's going on before they delve into code. You can read more on that in a post I wrote almost a year ago called "Who needs a software architecture document" but in essence the main motivation for documentation is that, assuming that the software is successful, it will outlive the team -- the people who built the software will not be the ones who will have to develop, maintain, and support it for most of the software's life.

If we agree that we need a software architecture document, the question is what to document and when.

There are two main "things" you can document in regard to architecture, the first is the obvious one -- the architecture itself. In my experience the most value can be derived from documenting recipes i.e. how to do stuff that is common in the architecture. These recipes can be a short description of the context and then a pointer to a test (or tests) and an implementation that exercises this. You can think of the recipes as a type of a tutorial to the architecture.

Other documentation-worthy elements related to the architecture are an overview and technology mapping (including what a developer needs to install to start working). The overview allows a newcomer to understand where to find what, the technology mapping allows for understanding what she needs to learn and install to be productive. Note that to be useful the overview should be at a higher level of abstraction than the code -- otherwise you run the risk of missing the forest for the trees or at least not saving any time.

It is obvious that documenting any of this before your architecture is stable more or less is useless, as a rule of thumb I would say this can be around the 5th-6th iteration -- assuming the team has to grow during the project. If the team stays stable for the duration of the project, this documentation can take place towards the end of the project (though I would probably add recipes to a wiki or something similar during the project as development patterns emerge).

The second "thing" you can document in regard to architecture are the decisions you decided against, in my opinion this is more important than all of the other items mentioned above. The reason for that, while it might take a while to understand a well-written software and infer its architecture it can be done, but it is virtually impossible to understand the options that were disqualified from looking at the chosen solution.

Understanding the options that weren't used can save time for the person reading that description, both in understanding why things are the way they are. Furthermore it can save time trying things that didn't work or provide clues to options when the circumstances change (since, as we all know, requirements change...)

The best time to document decisions you decided not to take is when you opt not to use them - this is when you remember best "why". For instance, in my current project we use x.509 certificates to authenticate clients and we use decided to use Kerberos tickets to authenticate components within the service. There's a reason for making that translation*,   there's also a reason for making the transition by replacing the client certificate with the edge component's credentials instead of mapping the client's certificate to a Kerberos ticket using an Identity provider*. we had two developers spike different options for two weeks until we came to the current solution instead of the more obvious choice of passing the x.509 certificate from the edge into the service and using the client's credentials. This question is likely to come up when/if someone else would take over the project, when the technology will be updated etc. Again, if we know why we didn't make that choice we can better decide what to do when the circumstances change.

To sum up, there are few architecture related issues that are worth documenting even in agile projects. some of them can be postponed some of them are worth documenting a little earlier. In any event it is better to document after the fact and to keep the documentation light.

Posted by Arnon Rotem-Gal-Oz at 05:53 PM  Permalink