The docs that survive two years and the ones that rot in a month
Picture inheriting a Laravel app where the previous agency left behind a 40-page Confluence wiki. It covers architecture philosophy, team values, and a diagram of their "service mesh vision." None of it matches the code. The deployment section references a Forge server nobody has credentials for, the job queue section describes Redis when the app is actually running on SQS, and the section on the CI pipeline was last updated before a migration to GitHub Actions that happened eight months earlier. We have walked into some version of this more than once.
Then, tucked in the repo's README, there is a single paragraph: "The payments table uses `transaction_ref` as the external ID. If it's null, the payment hasn't been reconciled yet. Don't delete rows — mark them `voided` or the accounting export breaks." That paragraph is worth two days of archaeology. The author wrote it during a fix, months before leaving the project, because they hit the bug and did not want the next person to hit it again.
The difference between documentation that lasts and documentation that rots is almost always whether the author was describing a decision or describing a state.
State documentation rots. Architecture diagrams, infra topology, "this service runs on ECS with 2 tasks," the list of endpoints, the ER diagram. These are snapshots. The day someone scales to 4 tasks or adds an endpoint, the doc is wrong and nobody updates it. We've written these ourselves and we've watched them die. The problem is that state docs look thorough — a reviewer sees a big diagram and assumes the project is well-documented. But a thorough description of the wrong state is worse than no documentation, because it delays the moment you realize you need to go look at the actual code.
Decision documentation survives. The deployment script that someone wrote because the existing one broke on a Tuesday — and the note they left explaining that the `ARTISAN_QUEUE` env var has to be set *before* the migration runs, because Laravel queues the job before the schema is ready. The `nginx.conf` rule that strips a trailing slash from the admin path because the React router chokes on it. These are things you learn once, at a cost, and the doc is how you avoid paying that cost again.
When we hand over a project now, we write almost nothing about state. The infra is in Terraform — that's the source of truth. The endpoints are in OpenAPI. The ER diagram is in the migrations. We write a lot about decisions. The README has a section called "Things that surprised us" — we log the gotchas we hit during the build, the workarounds we chose and why we chose them over the alternatives, and the places where we deviated from a library's defaults.
The kind of entry that belongs there: a SaaS dashboard built on a hosted auth provider where the connection name for social login has to be lowercase or it silently fails. The provider's docs say the value is case-insensitive. For that particular tenant configuration, it is not. That goes in the repo, with the support ticket number, so it is still there a year later when someone migrates the tenant and hits the same wall.
Notice what the entry is not. It is not a description of how auth is configured — that is in the environment files and the provider's dashboard, and it will change. It is a description of a behaviour that contradicts the documentation, which will stay true until the provider fixes it, and possibly long after.
The test for whether a doc will last two years: does it describe something true about how the system works, or does it describe how the system is configured? Configuration changes. Truths accumulate.