Defining and documenting a software architecture at the start of an Agile software project can be a challenging task, since not all decisions can be made when the project commences. Also, if a software architecture document is defined at the start of a project, then the document is not always updated as the project progresses.
The manifesto for Agile software development values the following:
Individuals and interactions over processes and tools
Working software over comprehensive documentation
Customer collaboration over contract negotiation
Responding to change over following a plan
That is, while there is value in the items on the right, we value the items on the left more.
Agile Manifesto
The second value from the Agile manifesto indicates that working software is valued more than comprehensive documentation, however documentation should not be neglected. Consider the below quote.
Agile methods are not opposed to documentation, only to valueless documentation. Documents that assist the team itself can have value, but only if they are kept up to date. Large documents are never kept up to date. Small, modular documents have at least a chance at being updated.
Micheal Nygard
Instead of creating one massive document, smaller or more modular documents should be created. This is when architecture decision records are useful. Micheal Nygard defines architecture decision records as follows
We will keep a collection of records for “architecturally significant” decisions: those that affect the structure, non-functional characteristics, dependencies, interfaces, or construction techniques.
Micheal Nygard
An architecture decision record (ADR) is a short text file, usually 1 to 2 pages long, that contains only one significant architectural decision, that is, each architectural decision made will have a corresponding ADR. If a decision is reversed, then the old ADR will be kept, however it will be marked as superseded with a link to the superseded ADR.
It is considered best practice to store architecture decision records alongside the code base in version control. An ADR should use a lightweight text formatting language like Markdown.
There are a number of templates that can be used to create an ADR. The most popular, simplistic and concise template to use is the template that Micheal Nygard defined. This format has 5 core sections.
1. Title – This is a short noun phrase, that is numbered, describing the architecture decision.
2. Status– Proposed, accepted or superseded.
3. Context – The context describes the problem and why this architecture decision needs to be made. The context can also include alternative choices.
4. Decision – This is the actual architectural decision combined with all the justifications. A decision normally starts with the phrase “We will …”.
5. Consequences – When an architectural decision is made, there are consequences, positive and negative, associated with the decision. This section documents these consequences and becomes the context after the decision is applied.
Due to the simplistic nature of an ADR, it makes it very easy to create an ADR, however there is an automated way of managing ADRs. adr-tools is a simple command line tool that can be used to help manage and version ADRs.
Example
The below document is an example of an ADR.
As can be seen, the ADR is very simplistic, concise and clear.
Summary
Agile methodologies are encouraging rapid software development to implement or enhance features as quickly as possible. These methodologies are not always applied to documentation. Architecture decision records is a great way to document and manage architectural decisions when embracing Agile methodologies.
Further information on architecture decision records can be found at the following links: