search

adr / madr

Markdown Architectural Decision Records
https://adr.github.io/madr/
Other
1.38k stars 395 forks source link

Can ADRs replace design docs and RFCs? #97

Open dineshdh opened 1 year ago

dineshdh commented 1 year ago

Can we just use ADRs instead of Design docs/RFCs for large change proposals? This will save people the effort of writing a design doc and then also recording the design doc or RFC outcome as an ADR, which seems a bit cumbersome.

socadk commented 1 year ago

You could but that you may encounter the "Everything is an ADR" risk that Michael Keeling points out. I call this phenomenon "Mega-ADR" in https://ozimmer.ch/practices/2023/04/03/ADRCreation.html

IMHO, the ADR records the decision and its rationale, serving as a journal of the decision making process and resulting actions. The resulting design is best described separately, in a design model or document. Separation of concerns applied to documentation... each design artifact has its specific purpose and target audience.

Coming back to your specific question @dineshdh will the readers of the change proposal or RFC need to know how the design evolved? or are they primarily interested in the result of this process? Both are valid information needs.

dineshdh commented 1 year ago

Thanks @socadk , I think that makes a lot of sense. So how would you practically implement both needs into your development practices. I kinda like the approach described in When Should I Write an Architecture Decision Record. I was wondering if you would amend this in any way. e.g. Would you draft an ADR first, then do the design docs, and once a design is selected finalise the ADR?