Ask HN: How do teams remember why infrastructure decisions were made?

gus_massa · 2025-12-20T16:25:35 1766247935

I send an email to the team, that has a few notes. It's actually an email for me in the future, and the notes are in case the future me forgot the details.

toomuchtodo · 2025-12-19T02:35:27 1766111727

ADR records. Store as markdown file(s) in the repo.

https://adr.github.io/

https://github.com/adr/madr

curious_sre · 2025-12-19T03:06:09 1766113569

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 · 2025-12-19T03:39:38 1766115578

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.

curious_sre · 2025-12-19T12:18:03 1766146683

That’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 · 2025-12-19T15:50:37 1766159437

As 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/sre-book/postmortem-culture/

gardenhedge · 2025-12-19T13:33:58 1766151238

Good 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.

mmarian · 2025-12-19T14:10:30 1766153430

Confluence pages, ADRs in github. Not perfect though.

d--b · 2025-12-19T10:29:30 1766140170

Ah I wanted to make a product to solve this problem. I posted here to see if anyone thought it was worth solving, but nobody seemed to care.

The way I wanted to do this is to create dashboards that would serve at the same time as infrastructure diagrams for documentation and live health monitoring.

Right now, most documentation solutions aren't used on a daily basis so become out of date, because people don't think about it when making changes and fixes.

And monitoring solutions only show you charts of things you're supposed to already know. They're very technically-oriented, and not business-logically oriented, if that makes sense. Like they'll tell you that process x is running on machine m, and that it's running out of ram, but nothing will tell you that process y that depends on x's outputs is going to fail as well.

mmarian · 2025-12-19T14:11:11 1766153471

After I read your comment, I remembered I posted about it too, and came to the same conclusion ^_^