I've found Architecture Decision Records (ADRs) to be a great way to document how and why a decision was reached within a codebase.
Unfortunately, design docs are underrated.
Most of the time, we did both. If we wanted to introduce a new process, refactor something, etc., I first do a Technical Proposal. Later, if it's accepted, I document it in more technical terms in an ADR, also mentioning the proposal, so it's clear why we needed it in the first place.
I've found Architecture Decision Records (ADRs) to be a great way to document how and why a decision was reached within a codebase.
Unfortunately, design docs are underrated.
Great post, Jordan! 🙌
I love ADRs too.
Do you do the ADR after the design doc or in replacement of it?
Most of the time, we did both. If we wanted to introduce a new process, refactor something, etc., I first do a Technical Proposal. Later, if it's accepted, I document it in more technical terms in an ADR, also mentioning the proposal, so it's clear why we needed it in the first place.
Ahh, makes sense. Thanks for sharing your approach, Petar