3 ms·
ADR records. Store as markdown file(s) in the repo. https://adr.github.io/ https://adr.github.io/ https://github.com/adr/madr https://github.com/adr/madr
by toomuchtodo 11mo ago
ADR records. Store as markdown file(s) in the repo.
https://adr.github.io/ https://adr.github.io/
https://github.com/adr/madr https://github.com/adr/madr
- curious_sre 11mo agoThat 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 11mo agoRarely 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.
- curious_sre 11mo agoThat’s helpful context, thanks. In practice, when incidents happen, where do people actually go to reconstruct the “why”? Is it mostly Slack archaeology and asking senior engineers, or is there something else that works better?
- toomuchtodo 11mo agoAs you said, chat logs, logging source of truth, and any context that can be provided by subject matter experts on the system(s) in question. Google's SRE resources on this topic are somewhat helpful, consider reviewing and evaluating for your environment. https://sre.google/workbook/postmortem-culture/ https://sre.google/workbook/postmortem-culture/ https://sre.google/sre-book/postmortem-culture/ https://sre.google/sre-book/postmortem-culture/
- gardenhedge 11mo agoGood but needs to be driven by a head of architecture type role incentivizing the practice. Otherwise it's a patchwork of records and largely ignored.