Hacker News Reader

Comment by azeirah | Hacker News Reader

If you adopt ADRs, you also need to adopt the practice of keeping them up-to-date and saying which ADRs are superseded and/or deprecated and by what newer ADRs.

An ADR directory is an immutable append-only log of transactions over the architecture, if the reduction operation over the set leaves a state with contradictions, then your set of ADRs is not well-maintained.

Not saying this is a fault of the devs, I think it's a fault of the people teaching ADRs and telling everyone they're great and you should adopt them. They take time to maintain and keep coherent.

If your team doesn't have processes to do this, then it's like a bank account that everyone can write to, but when the moment comes to withdraw money from it, it turns out a lot of the writes were done with monopoly money instead of real money, and you're suddenly in the red.

There are no easy shortcuts.

View on HN

This is so well said, thank you so much for summarizing it thusly in this thread!!

I completely agree, on everything: The records are not a one-and-done deal, they have to be maintained over the lifecycle of the codebase.

This methodology is trying to introduce records in the context of a practice in which they are maintained and used.

To your point, there are two aspects of this methodology that make it more sustainable:

- the entire corpus is deep-linkable at a granular level, and using path independent references — this allows interconnecting, referencing and ultimately ensuring the records and code keep strong mutual relevance by proximity

- the dense practice of including the why with a lot of granular detail, including discussions that built up to a final decisions (and what was considered but ruled out), this provides dense semantic context that helps future models that have no context almost become as knowledgeable about the architectural deliberations as if they had been there — this keeps the entire worth its cost of maintenance, because it provides what I call "epistemic continuity", a strong connection between the implementation and the rationale behind everyone of the design choices.

The idea is: "We can build code with models so quickly now, how do we ensure it's sustainable and well-architected and maintainable?" And this framework is trying to answer it by saying: "There is a methodology that introduces a cost overhead of O(1), but it provides long-term continuity guarantees."

Thank you again for stopping by, and providing the benefit of your experience with ADRs.

The documents therefore become another abstraction of the code that has to be maintained. Better then to include the decision record in each PR.

Reply on news.ycombinator.com