In some cases like clean written geometry algorithms the code _is_ the best technical documentation and attempts at verbal description would sound awkward and plausible become dated. In this case the purpose of the written docs is to offer enough context (possibly quite a lot) to understand the _why_ but the how is easiest to understand by reading the code.

I’m not arguing about your personal experience but these things are not absolutes.

The key thing is can a new developer jump in and understand the thing. Add enough docs until they facilitate this understanding as well as possible. Then stop documenting and point the reader to the code.

I disagree (a bit). It really depends on the person. I've know a good number of scientists who are great mathematicians but get confused as soon as they see code.

My point is that everyone is different. Documentation isn't just for developers and you never know who's going to contribute. It is also beneficial to have multiple formats just because even with a single person different ways make more sense on one day than the next. Having different vantage points is good to have. It is also good to practice your own mental flexibility[0]

I think the pytorch docs are a good example here. Check out the linalg module[1] (maybe skip the matrix properties section).

[0] This will also help you in the workplace to better communicate with others as well as makes you a better problem solver. Helps you better generalize ideas.

[1] https://docs.pytorch.org/docs/stable/linalg.html