[lowenbjer]

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.

[zain__t]

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?

[lowenbjer]

Check back in 2 years time, for now it has survived fine. Someone will be tuning it to write the documentation soon, instead of just blocking!

Jokes aside, i think LLMs will enable us to handle information in a much better and smoother way. We should use them!

[hiyer]

> documentation survives when it lives next to the code. 15+ years ago, this was pretty much the standard. Every decision - whether major or just a hack to handle a corner-case - used to be recorded in the code itself. Then tools like Jira and Confluence came in and these things moved to undiscoverable nooks and corners of the organization. AI search tools like Glean and Rovo have improved the discoverability, though I'd still prefer things to remain in the code.

[lowenbjer]

Agree!