I loathe nearly all man pages, they are written in a manner that is as over the top and an absolute chore to digest. I believe it is a form on programmer one-upmanship, it is largely unnecessary and stalls common usage massively.

I made this recently and tried very hard to make it so that the vast majority of people that could use the command line could grasp what it did, usage is trivial:

https://github.com/tux2bsd/freebsd-update-probe

I guess what I'm saying is I like documentation written for humans (which you do).