[sinzin91]

disclosure: I have a horse in this race

Beyond a certain scale, you can't keep a mental model of the entire system in your head. What matters then is accessing accurate, up to date information the moment you need it (troubleshooting an unfamiliar subsystem, making a cross-cutting change). Table stakes are IaC, APM, structured logging.

Code-generated docs sound great in theory, but a huge category of knowledge never lives in code (RFCs, deployment processes, how to get prod access). Humans have to write and maintain those. That requires a culture where people believe their effort matters (and ideally gets rewarded). Without that, docs rot regardless of tooling.

Then there's discovery. The docs often exist; they're just buried. RAG tools actually help here imo. When people can find what you wrote, you're more motivated to keep it accurate. As we increasingly rely on agents to tell us about our system, we're going to have to ensure the docs they're reading are not woefully out of date or inaccurate.