[boxed]

This assumes the docs written at the same time the code was changed is actually correct. This is an enormous assumption.

Documentation needs to be written as automated tests as far as humanly possible. I've worked towards this goal on iommi and it's been eye opening. Every time I run more code examples from the docs in the test suite I've found bugs.

[mikece]

> This assumes the docs written at the same time the code was changed is actually correct. This is an enormous assumption.

One would hope that the pull request/merge request review process would catch this. Ultimately the humans are the weak link in all of this but if the tooling could point out that DocumentationForThisFeature.md has a comment pointing to the class you just updated and you didn't assert one way or the other that the docs are still valid (not sure of the syntax of this... update the date on the class of an attribute like featureDocsLastUpdatedOrVerified="2020-02-04T14:51Z"?) could at least raise the "Oh yeah -- I forgot to update that!" awareness. You could even take it as far as making such an indication a reason to fail a CI/CD pipeline if documentation matters that much.

[boxed]

I wrote the docs for the code I myself wrote and I had bugs in it! And they were reviewer by a colleague. There were still bugs!

The the underlying code was changed, introducing more bugs.