March 13, 2026
Ghosts of Docs Past
How do you capture WHY engineering decisions were made, not just what?
New hire turns code archaeologist; commenters split: write it, test it, or bot it
TLDR: A new hire spent weeks hunting reasons behind past tech choices, exposing a documentation graveyard. Commenters split between automating decision write-ups via PRs and ADRs, reviving living design docs, stashing reasons in commits, or claiming tests should encode truth; everyone agrees missing 'why' slows teams and burns onboarding time.
At one startup, a senior engineer spent three weeks playing Indiana Jones in the codebase—not to learn what the software does, but why past choices were made. The ‘why’ was buried in closed pull requests (PRs), Slack threads, and the memories of teammates who’ve left. Attempts at documenting, like Architecture Decision Records (ADRs), PR templates, and a Notion wiki, fizzled. Cue a comment section meltdown.
The loudest camp says: automate or die. airspresso wants the capture and updates “automated,” even if humans type the words. CGMthrowaway takes it further: shove the ADR into every PR and auto-extract it into a log, turning paperwork into a pipeline. Another crew rallies behind process: _moof insists the rationale belongs in a living design doc that gets fed by tickets and meeting notes.
Then came the spice. rustyzig declares those “Redis vs memory” and “GraphQL vs REST” debates are just details; what matters is system behavior proven by tests (and type checks). That set off eye-rolls and amens. Meanwhile, willamin offers a small-team hack: put the reasons in one chunky commit message when merging.
The vibe? Everyone’s haunted by missing ‘why,’ and the crowd’s split between robots, rituals, and ‘let the tests speak’.
Key Points
- •A senior engineer spent three weeks uncovering the rationale behind past engineering decisions during onboarding.
- •Key unresolved questions include technology choices like Redis vs. in-memory cache and GraphQL vs. REST, and exceptions in enterprise auth flow.
- •Decision rationale was dispersed across closed PRs without descriptions, old Slack threads, and departed engineers’ knowledge.
- •Past attempts to systematize documentation—ADRs, PR description templates, and a Notion architecture doc—were not maintained.
- •The author asks for long-term solutions, possible automation, and whether such pain is common across teams.