My favorite example is Stripe. They've never skimped on docs and you can tell they've made it a core competency requirement for their team.
The one lesson I have learned over my career: Don't work in teams (or for managers) that rely on discipline to get things done. Every time I've encountered them, they've been using it as an excuse to avoid better processes.
Sure, some counterexamples exist. Chances are, those counterexamples aren't where a given reader of your comment is working.
At its core, a good test will take an example and do something with it to demonstrate an outcome.
That's exactly what how to docs do - often with the exact same examples.
Logically, they should be the same thing.
You just need a (non turing complete) language that is dual use - it generates docs and runs tests.
For example:
https://github.com/crdoconnor/strictyaml/blob/master/hitch/s...
And:
https://hitchdev.com/strictyaml/using/alpha/scalar/email-and...
No. Good docs will explain the context and choices made and trade-offs and risks and relations etc. All the things you can't read from the code. API docs can to a great degree be auto-generated, but not writing the _why_ is the beginning of the end.
You're right, it is a matter of culture and discipline. It's much harder to maintain a consistent and legible theory of a software component than it is to wing it with your 1-2 other teammates. Naming things is hard, especially when the names and their meanings eventually change.