1 yr. ago • 100%

Documenting Architecture Decisions

cognitect.com Documenting Architecture Decisions

I wonder if there are others using ADRs for documenting their decisions.

21 comments

We used this at my last company. We backported decisions into them as documentation. People sometimes referred to them, but not often. It was hard to take what was a huge list of docs, some of which had been obviated by others, and truly grok them all. But I don't have a better idea for how to solve the problem. I would say it worked OK, but not great.

5
We use them at my company. I love how new engineers can't just come into our codebase and start doing huge refactors. ADRs kind of force them to explain their rationale. We also use them to upvote on whether an architectural change should be implemented or not.

5
- How difficult would you expect it to be to go back and produce ADRs for significant decisions in the past that resulted in the current architecture and structure of a small-medium sized project?
  
  2
  
  It may be difficult if the context behind those decisions are lost, but I imagine it can be doable for a smaller company, assuming the amount is reasonable. And ofc, there's always a chance the extra overhead may piss off a few engineers 😆
  
  1
- That sounds like you have slightly deviated from the simple ADR format (maybe not)? How do you perform the voting?
  
  2
  
  We just thumbs up the PR for an ADR if we're in favor of it. Does that differ from the ADR format?
  
  3
We use them. They have been incredibly helpful. The concept has spread to our product team making product decisions!

4
- We started with with ADR, but then we also started using RFCs to discuss designs. Having this sort of minimal documentation really helps us in many aspects.
  
  2
This is the kinda stuff I expect to find in this kind of community! ADRs are a good topic that can help teams act more mature.

And less general career questions and low-level "what technology should I learn" 🤔

4
This is interesting! I think conceptually we've tried stuff like this but never had a standard to point to. I think it also helps figuring out when and why a decision was made even if you are an "expert", as we all forget

3
I haven't seen mentioned in the post but there is a template for this here: https://github.com/adr/madr/

Also those things are pretty much mandatory when you write surgical or healthcare devices. They have weird names like SDD (detailed design) or SDS (detailed specifications). There is some info about it here: https://en.wikipedia.org/wiki/Software_design_description

2
- The post is what started the whole ADR wave in the industry (I think there was also a conference talk by him). https://adr.github.io/ has a list of resources (templates, articles, examples, tools, etc.).
  
  2
I like them a lot. Sometimes I use it as an agenda to sell an idea in a meeting. Othertimes I backport them after a decision has been made. It’s the context that drives a decision that easily gets lost to time.

I’ve been burned when a technical decision hurt us down the road and no one could really remember why we made it to begin with.

2

You've viewed 21 comments.