Would agree that the higher level documentation (diagrams, process interaction, etc.) can be written down once the dust settles.
Would agree that the higher level documentation (diagrams, process interaction, etc.) can be written down once the dust settles.
And if the team is properly collaborating, they are linking issues and merge requests with commits, providing historical snapshots of the ever evolving context!
They're just not designed for pedagogy in the same way docs should be.
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.
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.
Naming is hard. So is documentation. I did that just to trigger fallacy trolls, but sometimes smart naming is documentation. Maybe that hard work of naming is worth it.
Verifying that code flow makes sense via code review guarantees that code is documented well enough.
As does handing it to the intern, without any "training," and asking for a new feature. Or an expert in a different part of the stack but not this code. As does playing "spot the bug" and having most people understand the code, even if they don't see the bug. Heck, just passing through some linters and style analyzers can get you pretty close to not needing documentation.
There are many things that count in different ways. What does your team want/need/desire? Does the answer change when it's someone else's code and their own?
The flip side is a lot of prose in the human lingua franca wherever you code. (Probably American English but that's another screed.) That means people with coding chops also need literary chops. Or a friend who has them. It means that you're not only judged on how well you solve problems with code, not only with how easy that code is to inherently understand, but also judged on how well you can explain to someone else what it is and how to use it.
If you really need that heavy documentation, hire a tech writer. Just like you probably specialize in a kind of dev, you can find specialists who specialize in making things make sense to devs.
(I often recommend diagrams just to make boundaries clear to everyone "at a glance" but don't think those really count as documentation in this context.)