Introducing ADRs in a heterogeneous team of five
Context
As part of a 9-month engagement, I had the opportunity to work for an industrial client — what we commonly call a “large enterprise” 😏.
And large enterprises often mean 👀 …
History, procedures, and documentation. A lot of documentation. I’d even say: an insatiable need to document everything that is done.
In this kind of structure, you also find significant inertia. Change takes time.
It’s also common to see regular turnover in development teams — sometimes partially or fully outsourced to consulting firms.
In that context, documenting knowledge transfer becomes critical, both for onboarding costs and for newcomers’ cognitive load 😶.
As a result, some drifts can appear: over-documentation, “just in case” documentation, and requests for developers to update SharePoints, Excel files, Google Drives, etc.
As developers, we don’t particularly enjoy working across such a wide range of documentation tools 😶.
The team
- 1 developer with 10+ years of experience
- 1 junior developer with 1 year of experience
- 1 junior developer fresh out of school
- 1 lead developer (me)
- 1 project manager (similar to a product owner)
- 1 department manager
- 1 scrum master
A documentation approach through ADRs
What is it?
ADR stands for Architecture Decision Record.
It is a document type and format that helps keep a history of decisions made on a project — similar in spirit to RFCs.
Red Hat published a very good article on why we should use ADRs to document architecture decisions; I recommend reading it.
The goal of an ADR is to record a technical choice within a given context (political, economic, or social). This later helps explain why a decision was made — especially when it gets challenged by a newcomer (and it will 😄).
Introducing ADRs makes documentation easier for developers (and even motivates them to do it 🙂).
There are dozens of ADR templates. I recommend reviewing them as a team and choosing the one that best fits your context to start with.
Don’t make the mistake of bringing heavy artillery immediately! You can always evolve the format after a few weeks or months of practice (isn’t that agility? 🙌).
A small SWOT matrix
To present this approach, we worked together on a SWOT matrix — both to convince external stakeholders and to validate our own direction 😁.
⬆ Strengths:
- Records the decision and its deciders
- Captures context, which increases accountability
- Helps newcomers understand past choices
- Easier document archiving
↗ Opportunities:
- Simplifies documentation for developers
- Keeps documentation close to developer tools (e.g., in a Git repo)
⬇ Weaknesses:
- Sharing with external stakeholders (may require duplication or rewriting)
↘ Threats:
- Overthinking
- Recording everything (including non-architectural decisions)
Where should these documents live?
Important question!
Since developers will write these decisions, ADRs should live as close as possible to their daily tools.
Why? Because we need to stay motivated to document 😇.
Ideally, ADRs should be stored in Git, within the project repository.
In our case, we made a pragmatic choice: we placed everything in a wiki.
Azure DevOps (ADO) was already used for project and source management, and non-developer stakeholders were accustomed to ADO wikis.
Template example
We looked at existing templates — why not leverage prior experience?
We ended up using this ADR template.
What we liked is that it captures multiple options, with pros and cons for each.
Below is an example ADR kept in English (as developers, we’re expected to be comfortable with English):
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
# 001 - Application hosted as a Windows Service.
## Title
Application will run as a Windows Service.
## **Status**
Accepted.
## **Summary**
**In the context of** the technical requirement of the production and usual habits of internal developers teams.
**facing** the need of being homogeneous between usages
**we decided for** running the application as a Windows Service.
**and neglected** any other options
**to achieve** better maintenance and collaboration with the infra team.
## **Context**
The targeted production stack is based on Windows Server.
We would like to have a industrial way to deploy it and ensure us that the infrastructure teams can easily apply their maintenance and monitoring plans.
The actual dev teams already use Windows Services but still, we would like to record the decision.
## **Options**
### Define app as a Windows Service
Good, because concept is already used by actual dev teams.
Good, because solution is native and supported by the targeted stack.
Good, because it is reliable.
Bad, because we can't precisely control if, other services required by our app, already run.
## **Decision**
Given the fact that:
- Actual dev teams is already used to manage Windows Service
- All the good points above
We choose to deploy and host our app as a Windows Service.
## **Consequences**
- we must find an efficient way to configure our CI pipeline to create the targeted package
- we should configure our CD pipeline to include a deployment script
- we should find a way to automatize the Windows Service creation, update, removal and the launch of it
### Deciders:
- ...
- ...
### Last state updated date: 03/01/2024
Conclusion
There is no single magic solution that solves everything.
For example, in some teams, a pull request / merge request is itself considered an ADR.
A decision is living: it can and should be updated over time. It may become deprecated by a newer decision — which should be reflected in its status with a link to the new ADR.
A useful reflex when deciding whether to record a decision is to ask whether it can be measured — for example using the SMART principle (yet another one 🤷♂️!).
Yes, this worked well 👍.
But in other projects, with different political, financial, or social constraints, other approaches might have been more appropriate.
And if we succeeded in this change, it was thanks to all stakeholders:
- the initiator of the solution 👋
- the team’s willingness to challenge the existing setup
- the pragmatic choice to duplicate information when needed
Resources
- https://www.redhat.com/architect/architecture-decision-records
- https://blog.octo.com/architecture-decision-record/
- https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
- https://blog.wescale.fr/bonnes-pratiques-pour-%C3%A9crire-un-adr
- https://www.linkedin.com/pulse/what-architecture-decision-record-adr-do-i-need-how-useful-atmakur
- https://github.com/joelparkerhenderson/architecture-decision-record
- https://martinfowler.com/articles/scaling-architecture-conversationally.html#WhentraditionalApproachesToArchitectureBreakDown
Have I already mentioned my favorite universal rule, inspired by the scouts? Probably not enough 🙂.
Try to leave this world a little better than you found it. (Baden-Powell)