The moment you write documentation it becomes stale. It's additional debt you've incurred and the upkeep must be payed every modification to the code.

That doesn't mean you should skip it - but it's vital to recognize the costs.

When I joined my current company they had extensive documentation on several systems, all of it outdated, stale or even just straight up wrong. I wasted cumulative weeks depending on other programmers to have properly documented things.

It's still worth doing: but you _must_ continually pay the debt down.

The fix for that is to keep the documentation in the same repository as the code it documents, and then to enforce that it gets updated as part of your code review process. Don't let a PR land if it doesn't also update any relevant documentation at the same time.

Keeping documentation in a separate system - like a wiki - is an anti-pattern in most cases. It leads to documentation that nobody trusts (and hence nobody consults) because it inevitable falls out of sync with the system it is documenting.

Plus... LLMs are good enough now that having one automatically check PRs to warn if the change affects the existing documentation might actually work well enough to be useful.

That is why I like the idea of having as much of the documentation as possible in code. Tests that describe how things are supposed to work, infrastructure as code the describes the parts of the system and so on. Then you are forced to keep them up to date.