First of all, I want to start off by saying I don't think that the Python documentation is as bad as some rather vocal opponents think. I very rarely have to look at the source to figure out what the docs meant. And even when I do it's usually for some complex reason and it for the C API, not the Python API.
That being said, they could still stand to be improved. I think there are two key ways that this can be done. The first one is to move the docs over to a simple, semantic markup format. As of right now the docs are maintained in LaTeX, and that's fine. I know LaTeX so I have no issue working with them. But I did learn LaTeX solely so that I could work on the docs. Plus it adds a bottleneck to doc changes since it ends up requiring someone with LaTeX knowledge to help with any doc changes instead of letting anyone tweak them.
I want something simpler to allow more people to be able to hack on them. But it can't just be something as simple as just adding emphasis and such for a function name. We need something that can confer semantic meaning. This means having a specific markup to specify that some text is a function signature and this other text is the name of a class and here are its methods. This especially becomes important for stuff like the C API where you need to make sure to include whether a function returns a new or borrowed reference of an object or what the return value that signals an error is. By having semantic markup you make that part of the requirement of the definition so you don't forget it. It also allows you to mark up names in a general way for automatic references and indexing.
But do realize I want something light. So defining a Python function could be ``@def func(a, b=None, c='hi')``. For C code it could be ``cdef_py func(a:o|b:s, c:s)(o)(borrowed)``. The point would be for them to be written much like they exist in their definition in the code with perhaps a little bit more detail as needed (which is why the C API definition looks so much different than the Python version; need return value and either details on the type of reference returned or what signals an error). Something that makes sense from how the code is going to be displayed by the docs or actually written. Most of this could even be auto-generated from .h files or __all__ values or whatever. That way the details just need to be filled in.
That's when you get to community participation. Now I am not a supporter of turning the docs over to wiki maintenance. I think the official docs need more oversight than that. But what we could do is have a little link by each function, method, module, or whatever definition called "Suggest a Change". That would give you a window pop-up with the text as it appears now in a textarea box along with all current suggestions. You can then edit the markup to have that be a newly suggested version and vote for other proposed changes. Then approved doc maintainers (which can definitely be more than just people with commit privileges) can go through the suggestions and either apply the suggestions or deny them and clear out the suggestions. That should allow for the community to help make the docs better while keeping quality control in place.
