Why Documentation Is Architecture

Most of the engineers consider documentation as an after-thought; a README on a finished system written in the final 20 minutes before a PR gets merged. That's the wrong way to do this relationship. Documentation is not a description of architecture. It is part of the architecture, and marking it as separate is the cause of so many rotting systems, which still pass all tests. The compiler doesn't care, your team does It could be a consistent codebase and yet it be undocumented garbage from the point of view of anybody who didn't write it. Only one sort of correctness is enforced by the compiler (or interpreter): does this code perform the operation that the instructions say it performs. It doesn't weigh in on why a specific table contains a deleted_at column, versus a hard delete, or why a service tries 3 times with exponential back-off, versus 5 times with a fixed interval. Those decisions include constraints that are not apparent in the diff, regulatory, historical, or performance. If these are only in the mind of the programmer who wrote them, the actual architecture is partially undocumented, and these constraints will be breached as soon as someone else messes with the code when it is under a tight deadline. Architecture is not only the shape of your services and schemas, it's the set of decisions and constraints that shape stayed within. Undocumented constraints are like walls that we don't see, or know about. They are walked through without anyone knowing they exist, and one of the assumed conditions is broken at a time. Documentation as a design artifact, not a report Good documentation should be done prior to and/or in the midst of implementation, not after. When writing a design doc that explicitly states the problem, the options you considered, the one you selected, and the tradeoffs you made, you are actually doing real design work, you are making mistakes in your thinking process that would only become apparent during production. There have been more ti