Decision Recording … The Agile Way
The term Agile Management is applied to an iterative, incremental method of managing the design and build activities of engineering.
Agile’s Take on Documentation:
There has always been a battle with code vs documentation in agile frameworks.
The agile standards state documentation should be “Just Good Enough”.
The Agile development methodology is in no way anti-documentation.
It simply reminds teams to document no more than necessary, and when necessary, keeping documentation as simple as possible.
The idea is to choose a format and level of detail that allows change and delivers just enough value to keep the team moving forward in the right direction.
We spend a good amount of our time with TDD (Test Driven Development) and code commenting which are crucial and important for the project.
The part where things get confusing is when there are historic architectural decisions that change the same piece of code. You can either blindly accept the decision or you can blindly change it without fully knowing why it was there in the first place. Both are not ideal solutions.Curious to see if there was an answer for this issue, I researched on agile architecture decision logging and stumbled upon some great techniques.
This is when I came across
Lightweight Architecture Decision Records
- It’s simple and minimalistic.
- It had all the components of agile, for “architecture decisions”.
- The concept is a simple logging system for architectural decisions living alongside with the codebase.
Every six months or so, ThoughtWorks publishes its Technology Radar. What started as an interesting experiment has turned into quite a notable publication.
ThoughtWorks came up with this as one of their Techniques to adopt in May 2018 in their Technology Radar.
Components of an Architecture Decision Record:
- Title Short noun phrases giving name to the architecture decision needed.
- Status What is the status, such as proposed, accepted, rejected, deprecated, superseded, etc.?
- Context What is the issue that we’re seeing that is motivating this decision or change?
- Decision What is the change that we’re proposing and/or doing ?
- Consequences What becomes easier or more difficult to do because of this change ?
Example
The ADRs can live in the project repository under doc/arch/adr-NNN.md
Some More examples of ADRs:
Some examples for an ADR https://github.com/npryce/adr-tools/tree/master/doc/adr
When there are Decision Records that impact more than one codebase for instance microservice logic change, we can have a single ADR that documents the change live in a codebase that is dedicated for all the ADR changes. Some companies prefer having it in their engineering wiki. I guess it is more of a personal preference at that point based on how often your company updates the wikis and if your are consistent with reviews there.
In Closing :
Using this approach of architectural documentation has made me personally view architecture decisions in an agile manner — continuously changing and not necessarily a cumbersome task to keep track of.
There might be more organization needed around how the decisions are logged and probably have some time slotted to discussing architecture, but that is the whole point. Spending some extra time discussing and logging the decisions we take may save us much more time in the future revisiting good old codebases we once worked on.
Some have also extended this idea into Decision Logging that can be used in multiple other areas of Socializing the Decisions taken.
If you are interested to learn about it here is the youtube video below
I Hope this inspires you all to view Agile for Architecture the way you view it for Code.
Happy Logging till the next time !
