[the_af]

Plus you cannot really automate checks for documentation up-to-dateness.

I mean, with actual code you get some help from the tools. No silver bullet, but at least you have type checks, compiler errors, something. But with docs there's no way to automate checks to see if the doc is still relevant and accurate. And what terrible tools are there tend to lead to "boilerplate docs", like those javadocs mentioned in a comment elsewhere.

[dllthomas]

I mean, where it's applicable doctest is amazing. But that's not everywhere.

I've been wanting some kind of system to add references to tests to documentation, in the spirit of citation. Maybe I will build it at some point.