> In my experience, having worked at many large tech companies, design documents obfuscate, not enlighten. They become increasingly out-of-date as the code evol

> In my experience, having worked at many large tech companies, design documents obfuscate, not enlighten. They become increasingly out-of-date as the code evolves, creating anti-documentation that makes it take longer to understand code. Yes, yes, people should update design documents as the code evolves. Everyone knows that in practice, nobody updates old design documents. My experience has been the reverse, precisely because as you said.... no one updates old design documents. A piece of code with a design document at least has a historical record of what the original aims of the project were, and a written rationale for why they took certain approaches. Often you'll find a piece of code with a seemingly inane architecture and wonder "why is this so inane? were the the developers on drugs?". By reading the design document, you find out that sadly no the water fountains were not spiked with LSD in the 70s, but rather they were working around the performance characteristics of hardware that no longer exists and thus these baked in assumptions had reason and merit. Understanding the original why often illuminates the entire architecture, even if undergone a lot of changes because the original skeleton still remains. I sort of look at it as Code Archeology, or maybe literary deconstruction as applies to code.