[jsdalton]

The “whys” here all sound sensible, but I’d be even more interested in _how_ people are implementing a process around ADRs, where you’re keeping them, etc.

At work we have a decent PR template that prompts people to provide context, alternatives considered, and underlying reasons for the change, which works pretty well. I’m trying about how or whether ADRs would function better, or if they would operate at a slightly higher level of change (i.e. for work that extends across multiple PRs).

I’d be interested in thoughts or experience people have, especially in medium or larger organizations.

[qznc]

I'm the software architect in a automotive project with ten teams. We use Confluence to write ADRs. We only use this process for changes which affect multiple teams.

Pro: Wysiwyg is great for editing it live in meetings, plugins like Gliffy are nice for diagrams, integration with Jira, accessible with a simple link.

Con: Not good enough for long term archival, so we export them to pdf regularly, wiki has no atomic commits.

We have a regular meeting where the team architects together discuss and ultimately approve these documents.

[rham]

I recently rolled off a sweet FinTech project with a Fortune 500 bank’s Emerging Technologies team which has the best ADR implementation I’ve seen thus far.

Just fyi, these ADRs, written in Markdown, are kept in separate repo with special Markdownlint rules applied to ensure consistent formatting. But what made this team’s ADR implementation stand out to me were not the technical details of how they were maintained, but rather the SOPs they’d strictly adhered to.

In essence, they had a very academic perspective on ADRs, viewing them more like a potentially publishable white-paper- not necessarily in terms of length or formality, but procedurally. The rule we followed was that a spike should lead to an ADR, which made writing an ADR much more of a build-measure-learn cycle and kept quality high, since authors weren’t scrambling to remember their entire thought process after the fact. This also greatly improved the quality of the spikes themselves, as we spent less time falling down rabbit holes. Basically, a spike became strictly a determination of either feasibility or implementation, with an explicit record of that the determination and the way in which it was made, as well as the other trade-offs considered.