Bitching about the documentation...

[rurpy at yahoo.com]

"Tony Meyer" <t-meyer at ihug.co.nz> wrote:
> > But, the standard responce of "don't complain, fix it yourself" is
> > bogus too.  There are plenty of people on this list willing to sing
> > python's
> > praises, for balance, there should be people willing to openly
> > point out
> > python's flaws.
>
> This makes no sense.  If you want to complain about Python, try a
> Perl list.  Why would a list dedicated to discussion about/help with
> a language need complaints about the language?

1. So group readers might have advance warning of problem
  they may run into.
2. To give potential adopters of Python a more even handed view
  of the language.
2. So developers will have a better idea of the problems the
  user base is actually having with Python.
3. To motivate those who are looking for a way to contribute.
3. So that people who want to express an honest opinion in an
  open forum won't feel intimidated.
I could probably think of more but I'm tired of typing.

I propose a couple additions the Zen document:
  Reality beats fantasy.
  Open discussion is better that propaganda.

> You might want to consider the difference between complaining and
> constructive criticism and suggestions, and which are likely to get
> better responses.

I agree within limits, but sometimes "constructive criticism" means
"play by our rules" which for me is outside the limits.  Also
non-constructive
criticism while not as valuable, is not worthless either.

> > Documentation is certainly one of them.
>
> FWIW, I have found Python's documentation to generally be excellent.

FWIW I find Python's docs to be OK at best, with some horrible
parts, and a lot of mediochre to poor parts.

1. I have seen recommendations here to use new-style classes.
I believe classes are at the core of Python, the entire language
is built around and rests on them.  Yet, unless I missed it,
new style classes are almost completely undocumented in
the Language Reference Manual.  This alone is sufficient
to condemn the documentation.

2.Section 2 of the Library Reference should clearly be in the
Language Reference manual.

3.There are way to few examples in the docs.

4.There are way to few cross references in the docs (for example
the datetime module doesn't even mention the existence of the
time" module.) [I double checked before posting and see this is
no longer true, but I think it is still true in many other cases. ]

5.Forward refernces (mention of things explained or defined
later in the manual) are seldom identified as such.  They should
be a link to the appropriate part of the manual.

6.There is often no notational distinction for terms used in a
general sense and a python specific technical sense leading
to confusion.

7.The writing is often too terse.  (To parapharse, it should be as
terse as possible but no terser.  I think it often violates the
that last clause.)

8.There is critical missing info.  (I lost many hours once because
the process module (or popen? I forgot) failed to document it
didn't do unicode.)

9.Many other small details, e.g is it neccesary for the one of the
most frequently used datatypes (string) to not appear in the
table of contents?  (That's not retorical, I really don't know.
Maybe it is, but if things could be arranged to that it did, it would
be better.)

> > And I was correcting a posting that explicitly said there was
> > exceptionaly
> > good information in that Howto.  That was just plain wrong.
>
> It is exceptionally good information.  The version that was at that
> link is somewhat dated (but still excellent for anyone using older
> versions of Python, or for those that need to remain compatible with
> older versions, and there are a lot of those people around), but the
> updated version is also excellent.  I'm sure amk will either update
> his page to point to the new one or update the content at some point.

No, it is not exceptionally good information.  It is outdated
information,
it does not say it is outdated, and it will lead to poor practice when
used
in the version of Python that it documents.  That clearly makes it "not
good".

> The point is that you're much more likely to improve things if you
> politely point out a problem and suggest a solution than simply make
> a complaint.

I did.  As for my original responce I think the suggestion was clear
if implicit: stop referring to outdated documentation as a "treasure".
The suggestion in my "update the damn docs" comment was quite
explicit I think.