It’s uncomfortable to notice that most of the documentation will die as most of the engineering teams have a lot of documentation written over the last year that no one trusts today.
Most technical documentation just describes the snapshot of that point in time, but the next day, the same documentation can be obsolete.
Most of the technical documentation covers everything, resulting in a hard-to-read doc with 30 pages that will take 2 hours to read. Also, there’s a wrong common format for these documents, as we just saw “what” changes, but we don’t have context for why the fellow developers did what they did.
These kind of issues arises a lot of questions: “Do they consider other options to solve this?”, “Do they know the tradeoffs of this implementation?”, “Is there something else that we should know from this decision?”.
Architecture Decision Records allow engineers to document single and significant technical decisions: what changes, why they changed, alternatives that were considered, and what we should observe from this change.
The format for an ADR has some conventions, but ideally, every team should decide which information is relevant for their project.
Using this approach, we can record the reasoning, not just the outcome.
This is an ADR redacted by me to explain to my teammates why we decided to unify the reschedule process for our email sending feature, as we consider that this approach will be easy to extend.
The perfect format for technical documentation does not exist, but ADR helps to close that inner gap to keep track of relevant information that changes about the business rules or architecture in the codebase.
