Documenting Design Decisions Using RFCs and ADRs (2020)
brunoscheufler.com
brunoscheufler.com
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 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.
Build people; not software
Build context; not documents
Build value; not lines of code
Fix root causes; not symptoms
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!
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.
It cuts down significantly on the number of things that has to be documented.