Ask HN: How do teams remember why infrastructure decisions were made?
4•curious_sre•2h ago
On teams I’ve worked with, we often run into systems where nobody really knows why certain configs, services, or architectural choices exist. Docs are outdated, Slack history is messy, and the people who made the decision are often gone. When something breaks, we end up rediscovering the same context over and over.
Is this just inevitable on long-lived systems, or do experienced teams have a better way of preserving this kind of context?
Comments
toomuchtodo•1h ago
ADR records. Store as markdown file(s) in the repo.
That makes sense.
In your experience, do ADRs actually get revisited during incidents or onboarding, or do they mostly exist as reference docs that people forget about?
toomuchtodo•38m ago
Rarely useful for incidents in my experience, mostly useful for onboarding those new to a codebase or part of a system. It’s a mechanism to preserve institutional knowledge that would otherwise evaporate due to not being represented as code; formalized documentation.
The benefit of this information existing in markdown files is this can also be used with LLMs and RAG if getting a natural language interface to the knowledge might be relevant to your enterprise.
toomuchtodo•1h ago
https://adr.github.io/
https://github.com/adr/madr
curious_sre•1h ago
toomuchtodo•38m ago
The benefit of this information existing in markdown files is this can also be used with LLMs and RAG if getting a natural language interface to the knowledge might be relevant to your enterprise.