[dragonwriter]

Not if the first step of updating the code is updating the documentation to reflect the intended state after the code update, preferably with embedded doctests that form part of the definition of done for the code changes.

Sure, if documentation is treated as an afterthought it tends to reflect that attitude.

[dllthomas]

In my experience, once you've got a bit of documentation, finding everything relevant to an intended change can be non-trivial and error-prone even if it's done first.

For documentation to remain relevant there needs to be some kind of process actually checking every part of it against reality.

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

[the_af]

> documentation is treated as an afterthought

Bingo.

Do note that people here on HN live in a bubble where, for example, writing tests (any tests, not even good tests) is a given. But out there in the world there's plenty of software coding, a lot of it in major companies, where developers think testing is some cute but useless thing they teach you in college and which can be safely skipped, and managers are completely oblivious about this. Same with writing useful documentation.