Dear Python Documenters,
As the subject line states, I am dealing with an ever growing general
frustration with the current Python3 documentation, that is making me
seriously consider consigning Python to the figurative landfill. The
search facility is next to useless for anything beyond a simple one-word
search, and completely ignores all relevant non-alphabetic characters
like the @ for decorators or the dunders.
In my perception the documentation has degenerated from being
comprehensible by a hobbyist (as was the case way back for 2.3) to
requiring not only a basic 4-year university degree, but also another 4
years of post-graduate studies in lingüistics.
Back in the days, the "Tutorial" was a compact overview of the most
relevant features and limitations that made it easy for a beginner or an
occasional hobbyist to find the basic information on keywords,
built-ins, variable and function naming limitations, as well as a
roadmap to more "advanced" features. Even the relevant dunder variables
were summarized in table format.
With the release of Python3 these summaries and easy to understand
explanations have more or less disapeared.
I had my start with computer programming way back in December 1985 with
the Commodore-64. The manuals were well writen in an easy to understand
common sense language. In the four weeks between receiving the computer
and the start of the user training course offered by the dealer, I had
taught myself to program even beyond the material covered in that 2-week
training course. So as a teenager I bugged the instructor for more
advanced tips and tricks. With-in a year I built a full-fledged database
system that ran on less than 31kB of memory and 170kB of disk space.
As a neurodivergent person living out in the wilderness, beyond the end
of the earth, I graduated from high school despite the school system.
But I was unable to prosper at university. Though I did teach myself
several other programming languages including dBase, C/C++, VB, SQL, C#,
Python, as well as a few markup languages like TeX and HTML/CSS, with
some basic scripting thrown in for good measure.
Having lived in virtual isolation for most of my life, I have had to
rely on vendor provided documentation for my knowledge and skills. 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 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.
And it gets even worse when I run afoul of simple limitation that is
burried in some extremely obscure corner of the documentation in the
form of a technical formula.
Or when I recall some snippet of information I encountered while
scouring the documentation for one issue, that would be relevant for a
new issue that I am dealing with. But for the life of me, I am simply
unable to find that information through the provided index and search
facility.
CASE IN POINT: I remember reading about there being a decorator that
automagicaly populates the __all__ dunder while working on a Unicode
codec problem. But now that I want to see if this decorator can be
relevant and/or helpful to my needs, I am unable to find the documentation.
Where is the summary table of all the available decorators with a link
to their relevant section of documentation?????
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???????? As well as a link to the relevant chapter
of the documentation.
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.
When I entered the search string “__init__.py” into the online search
box, it only produced hits to the “__init__()” function of classes.
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.
For those of you who have been full-time developers with and for Python
for the last five, ten, fifteen or even twenty years, many of these
things might be obvious to you. 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.
Thank you for “listening” to my rant. I wish you all successfull coding.
--
/"\
\ / ASCII Ribbon Campaign
X against HTML e-mail
/ \
PS: this mailbox is flooded with spam, that makes it very difficult to
find any relevant mail.
