They're just not designed for pedagogy in the same way docs should be.
They're just not designed for pedagogy in the same way docs should be.
For example, Rust has documentation which is executed as tests (doctests). That way, when the code changes, the docs change automatically.
To your mocks counter-example: How exactly would you propose to do it otherwise? If you write down an example which works now, how would you guarantee it still works if i.e. you don't use mocks but a say, a real database, which you then change.
You would be in the case of 3 green parallel lines which are red and intersect. In a powerpoint/doc you can write whatever you want. Doesn't actually need to be true.
And yes tests are not the best candidate to learn how to do stuff. The best candidates for this are out of band documents / media / training.