How do you capture WHY engineering decisions were made, not just what?
We onboarded a senior engineer recently strong, 8 years experience. He spent 3 weeks playing code archaeologist just to understand WHY our codebase looks the way it does. Not what the code does. That was fast. But the reasoning behind decisions: - Why Redis over in-memory cache? - Why GraphQL for this one service but REST everywhere else? - Why that strange exception in the auth flow for enterprise users? Answers were buried in closed PRs with no descriptions, 18-month-old Slack threads, and the heads of two engineers who left last year. We tried ADRs. Lasted 6 weeks. Nobody maintained them. We tried PR description templates. Ignored within a month. We have a Notion architecture doc. Last updated 14 months ago. Every solution requires someone to manually write something. Nobody does. Curious how teams at HN actually handle this: 1. Do you have a system that actually works long-term? 2. Has anyone automated any part of this? 3. Or is everyone quietly suffering through this on every new
Continue reading on Hacker News
Opens in a new tab


