Seeing more and more projects eschew code docs with the idea that "well architected code can be queried by LLMs" and stick to more functional runbook style docs. It really is unlikely that at any given point all of the docs of a project are up to date with the code.
I'm generally aligned with this, but it is predicated on the whole "well architected" code part.
The test can show intended use, show interesting corner cases, and I know it is up to date because it is constantly running and passing.
I think that is a huge underrated benefit of adding a lot more testing.
If I think a developer is going to ask a question of how something works, or about a corner case, isn't that deserving of a test, so they can just see proof of the answer to their question immediately rather than trying to re-derive it?
You know what, you are right on the money with that. I think if you expand to include functional/smoke/e2e tests, that covers pretty much everything documentation is supposed to be.
Just by running them you can measure if they are in or out of sync with the code (well, if they were written correctly).
I think unit tests are documentation in the same way that a Dockerfile is... it's not. The tests don't paint the bigger picture, explain why, etc.
That said, if you pitched me something like a Jupyter notebook style doc where tests validating the claims of the documentation were inline, I'd totally buy into that.
I'm generally aligned with this, but it is predicated on the whole "well architected" code part.