I'll let you in on the biggest unsolved problem in computer science. And no, despite the joke it's neither cache invalidation, naming, concurrency nor off-by-on

I'll let you in on the biggest unsolved problem in computer science. And no, despite the joke it's neither cache invalidation, naming, concurrency nor off-by-one errors. It's not even handling dependencies. It's knowledge transfer. I haven't seen any bigger problem until now and I haven't seen anything that comes close to a solution. Even though, I'm pretty sure of what is not a solution and that is (mid-level) documentation. Before I go taking that back a notch, let me clarify what I mean with that, as I've seen the cycle numerous times and have been at several of those points myself. "This is a mess, I don't understand anything... this isn't logical. We need to document everything! -> Sorry for that bug, I read your docs, but they were outdated. -> Sorry for that bug, I didn't even bother to read the docs, because most seemed outdated. -> We'll need to make sure the docs stay current, let's hire a technical writer / wiki gardener / wtf and introduce a process in our "Definition of Done (tm)" so it's all up to date -> (Actual Development mostly halted by now) -> Hey, welcome! Oh by the way, before your first commit, please read these 700 pages so we're sure you know what you're doing. Talented Junior Dev: !!! — Here's my resignation." The clear exceptions to this casual observation of mine are implicit and high-level documentation. Implicit includes: - self-documenting types and code ("Ronseal Code"): https://web.archive.org/web/20170426021541/https://peternixey.com/post/83510597580/how-to-be-a-great-software-developer https://web.archive.org/web/20170426021541/https://peternixe... - self-documenting gRPC and Swagger API schema - self-documenting constraints - Architecture and Schema diagrams - Specs and Design Docs - READMEs There's only a very limited case where mid-level docs make sense: - lots of consumers (public & commercial code) - stable systems with high fluctuation operations Other than that, this kind of documentation rots far too fast to have much net benefit at a high feature pace. The only tools that I've consistently seen work so far for knowledge transfer are simply hiring good and communicative people with a learning mindset, keeping attrition low by keeping them happy and productive, intro sessions, code reviews and growing reasonably slow while leveraging junior/senior (as in tenure) pairings for new projects. No kind of documentation in the world replaces the mental models of the people who architected a piece of software. Old guy rant end.