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 hire?
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 hire?