> a design doc written 2 months ago is never going to match the resulting code perfectly. That depends how you're writing design docs. If a design doc contains

> a design doc written 2 months ago is never going to match the resulting code perfectly. That depends how you're writing design docs. If a design doc contains arbitrary flowchars about what happens in the code, it will change. But if you come up with designs similar to design patterns, you can document the pattern once, and use it in your code the way you use a design pattern. Concepts that span a large codebase is also enormously paintful to figure out from reading the code. For instance object models / microservice architectures, complex state machines or security frameworks are hard to catch implicitly from reading the code.