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.

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

LLMs are great at writing unit tests.