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

For context, my engineering team is fairly small – no guarantees this scales well for larger organizations. I capture the reasons for decisions on why code was written a particular way or why a particular architecture was decided upon in commit messages. We follow a squash-and-rebase flow for commits, so each PR is ultimately a single commit before merging. During that squash process, I'll update the commit message to sometimes be a few paragraphs long. Later when I'm curious why we made decision in the past, I can use git blame to navigate back until the point where I can find the answer.

Doesn't really answer you question but IME this is sort of unavoidable unless you're massive and you can afford to have people who just document this kind of stuff as their job.

Reason being, a lot of this stuff happens for no good reason, or by accident, or for reasons that no longer apply. Someone liked the tech so used it - then left. Something looked better in a benchmark, but then the requirements drifted and now it's actually worse but no one has the time to rewrite. Something was inefficient but implemented as a stop gap, then stayed and is now too hard to replace.

So you can't explain the reasons when much of the time there aren't any.

The non-solutions are:

- document the high level principles and stick to them. Maybe you value speed of deployment, or stability, or control over codebase. Individual software choices often make sense in light of such principles.

- keep people around and be patient when explaining what happened

- write wiki pages, without that much effort at being systematic and up to date. Yes, they will drift out of sync, but they will provide breadcrumbs to follow.

My take after running engineering teams at multiple companies: documentation survives when it lives next to the code. File-level header comments explaining each component's purpose and role in the architecture. A good README tying it all together. If you compartmentalize architecture into folders, a README per folder. This works for humans, LLMs, and GitHub search alike.

ADRs, Notion docs, and Confluence pages die because they're separate from the code. Out of sight, out of mind.

If you want to be really disciplined about it, set up an LLM-as-judge git hook that runs on each PR. It checks whether code changes are consistent with the existing documentation and blocks the merge if docs need updating. That way the enforcement is automated and you only need a little human discipline, not a lot.

There's no way to avoid some discipline though. But the less friction you add, the more likely it sticks.

The git hook idea for enforcing doc updates is really interesting has that actually worked long term for your team or does it eventually get bypassed?

If you do these things:

* File issues in a project tracker (Github, jira, asana, etc)

* Use the issue id at the start of every commit message for that issue

* Use a single branch per issue, whose name also starts with the issue id

* Use a single PR to merge that branch and close the issue

* Don't squash merge PRs

You can use `git blame` to get the why.

git blame, gives you the change set and the commit message. Use the issue id in commit message to get to the issue. Issue description and comments provide a part of the story.

Use the issue id, to track the branch and PR. The PR comments give you the rest of the story.