Antoine Beaupr : Keeping track of decisions using the ADR model
The new process
We had traditionally been using a "RFC" ("Request For Comments")
process and have recently switched to "ADR" ("Architecture Decision
Record").
The ADR process is, for us, pretty simple. It consists of three
things:
- a simpler template
- a simpler process
- communication guidelines separate from the decision record
The template
As team lead, the first thing I did was to propose a new template (in
ADR-100), a variation of the Nygard template. The TPA
variation of the template is similarly simple, as it has only 5
headings, and is worth quoting in full:
- 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?
- More Information (optional): What else should we know? For
larger projects, consider including a timeline and cost estimate,
along with the impact on affected users (perhaps including existing
Personas). Generally, this includes a short evaluation of
alternatives considered.
- Metadata: status, decision date, decision makers, consulted,
informed users, and link to a discussion forum
The previous RFC template had 17 (seventeen!) headings, which
encouraged much longer documents. Now, the decision record will be
easier to read and digest at one glance.
An immediate effect of this is that I've started using GitLab issues
more for comparisons and brainstorming. Instead of dumping in a
document all sorts of details like pricing or in-depth alternatives
comparison, we record those in the discussion issue, keeping the
document shorter.
The process
The whole process is simple enough that it's worth quoting in full as
well:
Major decisions are introduced to stakeholders in a meeting, smaller
ones by email. A delay allows people to submit final comments before
adoption.
Now, of course, the devil is in the details (and ADR-101), but the
point is to keep things simple.
A crucial aspect of the proposal, which Jacob Kaplan-Moss calls the
one weird trick, is to "decide who decides". Our previous process
was vague about who makes the decision and the new template (and
process) clarifies decision makers, for each decision.
Inversely, some decisions degenerate into endless discussions around
trivial issues because too many stakeholders are consulted, a
problem known as the Law of triviality, also known as the "Bike
Shed syndrome".
The new process better identifies stakeholders:
- "informed" users (previously "affected users")
- "consulted" (previously undefined!)
- "decision maker" (instead of the vague "approval")
Picking those stakeholders is still tricky, but our definitions are
more explicit and aligned to the classic RACI matrix (Responsible,
Accountable, Consulted, Informed).
Communication guidelines
Finally, a crucial part of the process (ADR-102) is to decouple
the act of making and recording decisions from communicating about
the decision. Those are two radically different problems to
solve. We have found that a single document can't serve both purposes.
Because ADRs can affect a wide range of things, we don't have a
specific template for communications. We suggest the Five Ws
method (Who? What? When? Where? Why?) and, again, to keep things simple.
How we got there
The ADR process is not something I invented. I first stumbled upon
it in the Thunderbird Android project. Then, in parallel, I was in
the process of reviewing the RFC process, following Jacob
Kaplan-Moss's criticism of the RFC process. Essentially, he argues
that:
- the RFC process "doesn't include any sort of decision-making framework"
- "RFC processes tend to lead to endless discussion"
- the process "rewards people who can write to exhaustion"
- "these processes are insensitive to expertise", "power dynamics and
power structures"
And, indeed, I have been guilty of a lot of those issues. A verbose
writer, I have written extremely long proposals that I suspect no
one has ever fully read. Some proposals were adopted by exhaustion, or
ignored because not looping in the right stakeholders.
Our discussion issue on the topic has more details on the issues I
found with our RFC process. But to give credit to the old process, it
did serve us well while it was there: it's better than nothing, and it
allowed us to document a staggering number of changes and decisions
(95 RFCs!) made over the course of 6 years of work.
What's next?
We're still experimenting with the communication around decisions, as
this text might suggest. Because it's a separate step, we also have a
tendency to forget or postpone it, like this post, which comes a
couple of months late.
Previously, we'd just ship a copy of the RFC to everyone, which was
easy and quick, but incomprehensible to most. Now we need to write a
separate communication, which is more work but, hopefully, worth the
as the result is more digestible.
We can't wait to hear what you think of the new process and how it
works for you, here or in the discussion issue! We're particularly
interested in people that are already using a similar process, or that
will adopt one after reading this.
Note: this article was also published on the Tor Blog.
- 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?
- More Information (optional): What else should we know? For larger projects, consider including a timeline and cost estimate, along with the impact on affected users (perhaps including existing Personas). Generally, this includes a short evaluation of alternatives considered.
- Metadata: status, decision date, decision makers, consulted, informed users, and link to a discussion forum
The process
The whole process is simple enough that it's worth quoting in full as
well:
Major decisions are introduced to stakeholders in a meeting, smaller
ones by email. A delay allows people to submit final comments before
adoption.
Now, of course, the devil is in the details (and ADR-101), but the
point is to keep things simple.
A crucial aspect of the proposal, which Jacob Kaplan-Moss calls the
one weird trick, is to "decide who decides". Our previous process
was vague about who makes the decision and the new template (and
process) clarifies decision makers, for each decision.
Inversely, some decisions degenerate into endless discussions around
trivial issues because too many stakeholders are consulted, a
problem known as the Law of triviality, also known as the "Bike
Shed syndrome".
The new process better identifies stakeholders:
- "informed" users (previously "affected users")
- "consulted" (previously undefined!)
- "decision maker" (instead of the vague "approval")
Picking those stakeholders is still tricky, but our definitions are
more explicit and aligned to the classic RACI matrix (Responsible,
Accountable, Consulted, Informed).
Communication guidelines
Finally, a crucial part of the process (ADR-102) is to decouple
the act of making and recording decisions from communicating about
the decision. Those are two radically different problems to
solve. We have found that a single document can't serve both purposes.
Because ADRs can affect a wide range of things, we don't have a
specific template for communications. We suggest the Five Ws
method (Who? What? When? Where? Why?) and, again, to keep things simple.
How we got there
The ADR process is not something I invented. I first stumbled upon
it in the Thunderbird Android project. Then, in parallel, I was in
the process of reviewing the RFC process, following Jacob
Kaplan-Moss's criticism of the RFC process. Essentially, he argues
that:
- the RFC process "doesn't include any sort of decision-making framework"
- "RFC processes tend to lead to endless discussion"
- the process "rewards people who can write to exhaustion"
- "these processes are insensitive to expertise", "power dynamics and
power structures"
And, indeed, I have been guilty of a lot of those issues. A verbose
writer, I have written extremely long proposals that I suspect no
one has ever fully read. Some proposals were adopted by exhaustion, or
ignored because not looping in the right stakeholders.
Our discussion issue on the topic has more details on the issues I
found with our RFC process. But to give credit to the old process, it
did serve us well while it was there: it's better than nothing, and it
allowed us to document a staggering number of changes and decisions
(95 RFCs!) made over the course of 6 years of work.
What's next?
We're still experimenting with the communication around decisions, as
this text might suggest. Because it's a separate step, we also have a
tendency to forget or postpone it, like this post, which comes a
couple of months late.
Previously, we'd just ship a copy of the RFC to everyone, which was
easy and quick, but incomprehensible to most. Now we need to write a
separate communication, which is more work but, hopefully, worth the
as the result is more digestible.
We can't wait to hear what you think of the new process and how it
works for you, here or in the discussion issue! We're particularly
interested in people that are already using a similar process, or that
will adopt one after reading this.
Note: this article was also published on the Tor Blog.
How we got there
The ADR process is not something I invented. I first stumbled upon
it in the Thunderbird Android project. Then, in parallel, I was in
the process of reviewing the RFC process, following Jacob
Kaplan-Moss's criticism of the RFC process. Essentially, he argues
that:
- the RFC process "doesn't include any sort of decision-making framework"
- "RFC processes tend to lead to endless discussion"
- the process "rewards people who can write to exhaustion"
- "these processes are insensitive to expertise", "power dynamics and
power structures"
And, indeed, I have been guilty of a lot of those issues. A verbose
writer, I have written extremely long proposals that I suspect no
one has ever fully read. Some proposals were adopted by exhaustion, or
ignored because not looping in the right stakeholders.
Our discussion issue on the topic has more details on the issues I
found with our RFC process. But to give credit to the old process, it
did serve us well while it was there: it's better than nothing, and it
allowed us to document a staggering number of changes and decisions
(95 RFCs!) made over the course of 6 years of work.
What's next?
We're still experimenting with the communication around decisions, as
this text might suggest. Because it's a separate step, we also have a
tendency to forget or postpone it, like this post, which comes a
couple of months late.
Previously, we'd just ship a copy of the RFC to everyone, which was
easy and quick, but incomprehensible to most. Now we need to write a
separate communication, which is more work but, hopefully, worth the
as the result is more digestible.
We can't wait to hear what you think of the new process and how it
works for you, here or in the discussion issue! We're particularly
interested in people that are already using a similar process, or that
will adopt one after reading this.
Note: this article was also published on the Tor Blog.
Note: this article was also published on the Tor Blog.
You might see a verification screen pop up on more and more Debian web properties. Unfortunately the AI world of today is meeting web hosts that use Perl CGIs and are not built as multi-tiered scalable serving systems. The issues have been at three layers:

Current AI companies ignore licenses such as the GPL, and often train on anything they can scrape.
This is not acceptable.
The AI companies ignore web conventions, e.g., they deep link images from your web sites (even adding
Both R and Python make it reasonably easy to work with compiled
extensions. But how to access objects in one environment from the other
and share state or (non-trivial) objects remains trickier.
Recently (and while r-forge was resting so we opened GitHub
Discussions) a question was asked
Another year of data from Soci t de Transport de Montr al, Montreal's
transit agency!
A few highlights this year: