Agile and documentation? what gives? First things first documentation is not something that is prohibited by
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 - i.e. the
people that built the software will not be the ones that 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 together. 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.
*
It all has to do to to limitations of WCF in regard to the transports
we use (HTTP, MSMQ and TCP) and the request/reaction pattern
(asynchronous communication) we use.