Tried this many times, never got it to work properly.<p>I’m not sure if it’s because my teams are too small, or I’m bad at communicating.<p>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.<p>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).
At $job we're using the DACI framework for this kind of architectural decision making and it works really well!<p>The framework defines roles (driver, decision maker etc) which helps with the process.<p>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.<p>When the decision has been made, we go with it!<p>It's a really smooth process in practice, with very little friction. Way better than endless debates over and over on the same topic!<p><a href="https://www.atlassian.com/team-playbook/plays/daci" rel="nofollow">https://www.atlassian.com/team-playbook/plays/daci</a>
Author here, thanks for sharing!<p>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.<p>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.<p>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)).<p>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.