Mario L. Epp writes:

Dear Python Documenters,

As the subject line states, I am dealing with an ever growing general frustration with the current Python3 documentation, [14 lines of pure rant omitted] Even the relevant dunder variables were summarized in table format.

They still are summarized in the language reference. https://docs.python.org/3/reference/datamodel.html#special-method-names

As a neurodivergent person living out in the wilderness, beyond the end of the earth, I graduated from high school despite the school system.

You have my sympathy. I did prosper in the US educational system, but I always wondered why others did not. It never occurred to me to blame people -- I always thought that somehow the curriculum must be deficient. I still can't say how to fix it, though. :-(

Having lived in virtual isolation for most of my life, I have had to rely on vendor provided documentation for my knowledge and skills.

The PSF/Python community is not a "vendor". We sell nothing. We depend on users to provide support: financial contributions from companies (which mostly go to keeping PyCon cheap to attend), code and doc contributions from users who can, bug reports from those who can't.

But when that documentation abandons common language prose with illustrative examples in favor of a terse formulaic approach based on various linguistic theories, it becomes an excercise in frustration.

I have no idea what you're talking about. Can you provide two or three examples?

I tend to get a theoretical idea of what is supposed to be accomplished from reading the documentation of Python3 standard library. But unless there are some demonstrative examples provided with the documentation it takes me a lot of trial and error to make Python do what it should theoretically do.

Again, examples of classes or functions whose documentation frustrates you would help. I for one care about making documentation accessible to as many people as possible, but I have no experience of the frustration you feel. My frustration is almost always having to wade through many screens of a document to find what I need. I almost always want the documentation to be *more* concise. That doesn't mean it *should* be more concise, it means I need more specific description of what *you* need.

CASE IN POINT: I remember reading about there being a decorator that automagicaly populates the __all__ dunder while working on a Unicode codec problem.

I don't understand. __all__ is only useful when you want something other than the default of "all class and function names that don't begin with '_'". I doubt such a decorator exists, although I guess it could check for imported names and exclude those. Searching for "__all__" does work, and brings up nothing that seems relevant.

Where is the summary table of all the available decorators with a link to their relevant section of documentation?????

This might be useful, but searching for "decorator" turns up 59 pages, and the user can probably prune that down to a handful. You could just start with the first one and iterate. On the other hand, making an accurate list of *all* decorators is probably not something that can be done automatically. The type needs to be specified very carefully for that, and rarely is. So somebody will have to do it by hand. Maybe you could start!

Another CASE IN POINT: The documentation states that the user should NOT define any dunders beyond those defined by the language itself! But WHERE is the summary table (or list) with ALL the defined dunders and their basic function????????

It's in the language reference. See link above. If that's not good enough and you really want a line-per-dunder table, where should that be inserted?

Or the case of the “__init__.py” file????? The documentation only states that it has to exist in every directory of a package and is responsible for initiating all modules. But I have been unable to finde the relevant documentation regarding the structure and content of this so vital file.

What I quote above is the entire documentation of that file. The __init__.py file may be empty; its mere existence signals that this directory is a package. If it is empty, importing the package does nothing except provide a namespace for referencing the other files in that directory as modules. Any code present in it will be executed, but what that might do is entirely up to the package designer.

Collecting all the “__init__.py” files from the standard library and reverse engineering them to learn about the necessary structure and content is an imense waste of time and and excercise in extreme frustration.

It would be frustrating, since the various instances would likely be so diverse as to be useless to a new package creator, and in any case the empty file is sufficient for the primary purpose of creating a namespace. If there's any necessary code, that would be entirely dependent on the nature of the package. On the other hand, if you understand that existence of the file is important, but its content is almost arbitrary, seeing what others put in it can suggest "best practice". I don't know if that would work for you. If it doesn't, I'm not sure what to say except "put the stuff you think belongs in that file in it".

And seem irrelevant to spent time documenting. But keep in mind that the documentation also needs to be relevant to new-commers and occasional amateurs who need some comprehensive summaries or an easy way to find relevant information in the ever more extensive volumen of documentation.

We know what's relevant to *us*. You have to tell us what you need. "Everything everywhere all the time" is not helpful. Specific examples are helpful. Specific places you looked and didn't find are helpful. Steve