I’d certainly agree it would be much better served with a more structured, consistent format, as per Diataxis (which, as I frequently remind everyone, isn’t just about moving things around, but also improving the docs that are already in each of the categories—reference, in this case—to better serve their intended audience):
The only purpose of a reference guide is to describe, as succinctly as possible, and in an orderly way.
Respect the structure of the machinery
The way a map corresponds to the territory it represents helps us use the former to find our way through the latter. It should be the same with documentation: the structure of the documentation should mirror the structure of the product, so that the user can work their way through them at the same time.
In the case of code, this means arranging the sections of reference documentation to follow the architecture of the software, where possible.
Reference material benefits from consistency. Be consistent, in structure, language, terminology, tone.
This also helps a number of other things, such as when we’re trying to backlink in with the new PEP canonical docs banner.
This is certainly something I could help tackle, but I only have so many hours in a day and seemingly no end to the amount of docs that need help, not to mention everything else I’m engaged in just with open source.
As a core dev, I’m sure you’re busy too, but any help you could offer in this would I’m sure be much appreciated by all. I’m happy to help tag-team and review your PRs on behalf of the proofreaders/docs team as I did with Erlend’s that @ezio-melotti mentioned, which has been a very fruitful collaboration for us thus far.