Documenting Design Decisions Using RFCs and ADRs (2020)
brunoscheufler.comTried this many times, never got it to work properly.
I’m not sure if it’s because my teams are too small, or I’m bad at communicating.
When discussing technical specifications the most efficient way in my experience is to throw people into a room with a whiteboard and a few laptops and don’t let them come out until they’ve ironed out each other’s concerns; while this is uncomfortable, the alignment is unmatched by anything else I’ve tried.
In my current role we write detailed technical specifications in google docs; but the end result is similar, an ocean of tech specs that may be defunct or relevant or in draft status, dense reading and/or infinite questions once the document is produced (or worse: no questions at all! Which means either people didn’t understand it or they think it’s fine).
I also have this experience and I've gone as far as to build this understanding into how I improve teams.
I wrote myself a short alternative to the agile manifesto which includes the phrase "Build context; not documents". The documents are relatively worthless if you cannot get context across, so I also prefer these big sessions where everyone is in the room.
But I take it a step further. Instead of just having meetings where we discuss I start to drive in structure and formats. The team knows by the 3rd iteration what the process will look like: we do some customer empathy discussions, identify requirements, break down into something that looks a bit like a C4 architecture, and then break down into task dependencies. In each of those sessions I create the structure and coach the team in the workshop but also 1:1s to start using structured processes and less ad-hoc ways to communicate. For example, if we enter a requirements conversation about the customer and someone talks about MongoDB I tell them we need to defer the DB conversation. If we open a Miro board I enforce that we all use the same types of diagrams to discuss the same thing at the same level of abstraction (increase team discipline).
After the team learns the supporting structure for the process, the process takes less time each round. Lots of waste generated by confusion or off-topic discussions or non-critical points are removed or deferred to the right time. I did this with multiple teams in the same company, usually the first round takes 1-2 months, but the 2nd round takes 1 month, the 3rd can take 2 weeks, by the 4th round they can do everything without me (on average). They end up creating documents, but the difference is: now they have context, and they are "fully literate in a new language" which lets them move faster.
If you're interested, I wrote a bit about why I dislike the blind application of templates and process frameworks without context or "deep thinking" a few weeks ago: https://statagroup.com/profiles/brian-graham/request-for-fas...
The shared context in the brains of people working is all that matters when you want to drive outcomes.
Context is king.
Very nice article and many others under your profile too! Mind sharing the manifesto?
Of course, it's here:
Build people; not software
Build context; not documents
Build value; not lines of code
Fix root causes; not symptoms
At $job we're using the DACI framework for this kind of architectural decision making and it works really well!
The framework defines roles (driver, decision maker etc) which helps with the process.
So a document (with a template similar to an RFC) is made by the driver. Contributors read and comment on it, then after all questions have been answered, a final meeting is held to make the decision along with the approver.
When the decision has been made, we go with it!
It's a really smooth process in practice, with very little friction. Way better than endless debates over and over on the same topic!
Really cool link, I will need to try DACI. It reminds me a bit of RAPID ( https://www.bain.com/insights/rapid-tool-to-clarify-decision... ) but possibly more light-weight.
Author here, thanks for sharing!
Workflows like these are really specific to the environment you're working in, so take the post with a grain of salt and try to see what works best for your team.
With this said, a lot of companies work completely remotely (or in large parts) nowadays, so the importance of asynchronous communication and writing down decisions for future discussions cannot be understated.
I think we should strive for processes that don't take a lot of mental overhead, so removing friction where possible is key here, enabling everyone on the team to read and write their own RFCs and document decisions with ADRs.
My rule of thumb is: document informally (loosely following ADR) those decisions that had to be discussed more than once (encourage alignment) and that lead to a nonobvious change in process (to look up the choice(reference)/its context(problem to be solved)/consequences (advantages/trade-offs)).
It cuts down significantly on the number of things that has to be documented.
I've opted to just have a single document that mostly acts as an RFC, and maybe I'll put the decision down at the bottom. IMO the most valuable part of this whole thing is being able to read the comments and concerns from other stakeholders at the time the decision was being made. Keep it light and informal.