[mikece]

Why not just track the number of commits since the documentation has changed as a quick way of knowing which docs are most likely to be out of sync? Docs written in Markdown could have comment identifying which feature they belong to; code could similarly have a comment which feature they belong to. Doc pages could even dynamically display the number of commits on a feature since that doc page was updated... just thinking out loud here.

[vegetablepotpie]

You could gamify this by generating an update score. The more often and more consistently documentation is updated relative to commits, the higher the score. Nothing will be tied to the score, it’s just a number. It’s existence would incentivize developers to drive it higher. Sure you could get around it by just adding a space to the .md file, but at least then you’re opening the file and you may see something in there that needs a quick change anyways. The score would have done its job.

This would stop working if bonuses or compensation were tied to the score. The moment that happens, people will start writing hooks to update it with a space every commit, then it will be ignored by devs.

[enricozb]

I think it might actually be better to reward someone for updating extremely old documentation. Like if there have been N commits since this documentation was updated, it should be worth N points. Then people are incentivized to update the oldest documentation. Sure someone could wait for yet another commit and have it be worth N+1 points, but someone else might take it up.

[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.