How do you capture WHY engineering decisions were made, not just what?

Re:How do you capture WHY engineering decisions were made, n... by zain__t on Friday March 13, 2026 @04:59PM (#47369802)

The Q&A doc you're maintaining is fascinating you've essentially hand-built the thing I'm trying to automate. The 'Why Kafka?' entry is exactly the kind of decision that disappears when you leave. The search problem you raised is the core of what I'm solving — not dumping commits into a .md, but extracting structured decisions from the conversation that surrounded the commit: the Slack debate, the PR review, the ticket context. Then making it queryable by the code it relates to. You said you're not sure your process scales what happens to that Q&A doc if you leave tomorrow?

[ Parent | on HN ]

Re:How do you capture WHY engineering decisions were made, n... by physicles on Friday March 13, 2026 @06:08PM (#47370631)

If I leave, the Q&A doc probably never gets updated again.

We're in the process of trying to get as much stuff as possible into source control (we use google docs a lot, so we'll set up one way replication for our ADRs and stuff from there to git). That way, as LLM models get better, whatever doc gets materialized from those bits and pieces will also automatically get better.

[ Parent | on HN ]