Good Documentation Explains the Decision, Not Just the Code

A pattern I’ve seen many times in software projects is that documentation starts too late and documents the wrong thing. A team ships a feature, the code works, the tests pass, and everyone moves on. Maybe someone adds a README section, maybe not. If they do, it usually explains how to run something, how to call an endpoint, or what a component does. That kind of documentation is useful, but it often misses the part future developers need most. It misses the decision. Six months later, someone opens the same part of the codebase and asks the usual questions. Why is this data model shaped like this? Why is this rule handled in the backend instead of the frontend? Why is this integration synchronous? Why does this permission check live here? Why did the team choose this simple approach instead of something more flexible? The code can show what exists, but it rarely explains why it exists. That is where a lot of engineering context disappears. The Problem Is Not Always Missing Documentation When people complain about documentation, the usual diagnosis is that there is not enough of it. The README is outdated. The setup instructions are incomplete. The API docs are missing examples. The architecture diagram no longer matches reality. All of those problems are real. But I think there is another documentation problem that is easier to miss: the docs describe the system without preserving the reasoning behind it. This matters because software is full of trade-offs. A piece of code may look strange because it was written badly, but it may also look strange because it was solving a constraint that is no longer visible. Maybe the team chose a simpler data model because they were still validating the product. Maybe they avoided a generic abstraction because they had only one real use case. Maybe they accepted duplication because the two workflows looked similar but were expected to diverge. Without the reasoning, future developers have to guess. That guessing creates waste. So