Do you feel bad because of the Python docs?

[emile]

What it could have is better searching capability and a way to see
more examples. Examples would clutter the documentation so maybe they
should be collapsible, but you can never have enough examples.

A good resource (although only covering up to v2.3) is effbot's guide to
the standard library available at

http://effbot.org/zone/librarybook-index.htm

It's pretty much _all_ examples.

Emile

 

[Mark Janssen]

On Tue, Feb 26, 2013 at 4:54 AM, Steven D'Aprano <

There's no doubt that one of PHP's strengths, perhaps its biggest
strength, is the good state of documentation. But should we feel bad
about Python's docs?

I don't think so at all. I think the python docs are quite well organized.
Who googles for python knowledge when you can just go to the official site
and use the doc search?

Mark

 

[Rick Johnson]

Just to throw in my 2c -- in the same way that 'a picture
is worth a thousand words', an interactive interpreter is
worth volumes of documentation (especially one with such a
nice help()/__doc__ functionality).

Yes! I don't even know why people care about the Python docs anyway. One ofthe most under-appreciated (and maybe even unknown) aspects of the Python language is the power of doc strings and the help function. Not to mention the awesome introspection capabilities via a few built-in functions:

id(obj)
isinstance(obj, type)
issubclass(obj, klass)
repr(obj)
type(obj)
bool(obj)
dir(obj)
...


As for the docs:

I would say that if you are searching for a "particular something" (and thehelp function has failed you), then skip the docs and use Google instead. The docs only seem to work well when read in a "linear" fashion; with exception of the "global module index" and the "language reference" sections.

As for the "official tutorial", do yourself a favor and DON'T read it (or never read it) until AFTER you are comfortable with python. It's not so muchthat the tutorial is lacking, it's more that the tutorial uses poor example code and as such is an abomination. That's my opinion anyway. There are tons of great python tutorials on the web.

You aren't sure what errors are thrown by a particular
function? Fire up an interpreter and feed the function
junk. You'll get your answer faster than you can Google,
and often learn neat stuff along the way.

Yes! Interactive sessions are what make python so damn great! If you don't have an editor window and a shell window open when writing (python) code, you are doing something wrong.

(I recall one of
RR's posts that actually had some good tips to learn-via-
interpreter).

I don't remember the exact thread off-hand, but i must admit you can find loads of great information in my threads!

 

[Rick Johnson]

Just to throw in my 2c -- in the same way that 'a picture
is worth a thousand words', an interactive interpreter is
worth volumes of documentation (especially one with such a
nice help()/__doc__ functionality).

Yes! I don't even know why people care about the Python docs anyway. One ofthe most under-appreciated (and maybe even unknown) aspects of the Python language is the power of doc strings and the help function. Not to mention the awesome introspection capabilities via a few built-in functions:

id(obj)
isinstance(obj, type)
issubclass(obj, klass)
repr(obj)
type(obj)
bool(obj)
dir(obj)
...


As for the docs:

I would say that if you are searching for a "particular something" (and thehelp function has failed you), then skip the docs and use Google instead. The docs only seem to work well when read in a "linear" fashion; with exception of the "global module index" and the "language reference" sections.

As for the "official tutorial", do yourself a favor and DON'T read it (or never read it) until AFTER you are comfortable with python. It's not so muchthat the tutorial is lacking, it's more that the tutorial uses poor example code and as such is an abomination. That's my opinion anyway. There are tons of great python tutorials on the web.

You aren't sure what errors are thrown by a particular
function? Fire up an interpreter and feed the function
junk. You'll get your answer faster than you can Google,
and often learn neat stuff along the way.

Yes! Interactive sessions are what make python so damn great! If you don't have an editor window and a shell window open when writing (python) code, you are doing something wrong.

(I recall one of
RR's posts that actually had some good tips to learn-via-
interpreter).

I don't remember the exact thread off-hand, but i must admit you can find loads of great information in my threads!

 

[Chris Angelico]

I don't think so at all. I think the python docs are quite well organized.
Who googles for python knowledge when you can just go to the official site
and use the doc search?

I'm not sure if you're trolling or not... The python.org search is one
of its weakest attributes; on the main http://python.org/ search, it's
now been replaced by a Google site-search, but the box on the side in
http://docs.python.org/ still gives the annoyingly slow internal
search. So no, I don't go to the official site search, I use Google
(with or without siteython.org to restrict the results - most often
without).

ChrisA

 

[Terry Reedy]

I would assert it isn't very kind to those even with basic fundamentals.

For example, under precisely what circumstances does int() raise
TypeError? You won't find that under either int's documentation, or
TypeError's documentation, you have to look it up under __int__, which
is _not_ a basic fundamental. And rather than helping you along the
way, the documentation for int() actively misleads you by its
implicature that the only acceptable types are strings, ints, and
floats. And then even if you have the foresight to remember "oh yeah,
isn't there a special method for this?", you have to find the
documentation for __int__, which is itself is three quarters of the
way down this massive page:
http://docs.python.org/2/reference/datamodel.html

Have you opened an issue, or checked for existing issue? I would be open
to the idea that entries like that for int should not be overly type
specific and imply that the defaults are the only possibilities.
Perhaps there should be a cross-reference to corresponding special
methods. Perhaps that idea might be opposed. I am not sure. Perhaps
Built-in Functions needs a bit more general explanatory text at the top.

 

[Terry Reedy]

I think the issue with python documentation is that it ignores the 95/5
rule: 95% of people who land on a module's page are only looking for 5%
of its information. So ideally it'd be separated in two different pages
or two sections of the same page, something like:

===============================================================================================


Hi, chances are you are the 95% of people who isn't interested in the
intricacies, obscure edge cases et cetera. Here are the few common use
cases for this module:

...

...

...

===============================================================================================


Hi, the section above obviously did not suit your needs, so you must be
in the 5% who has no choice but to either read through or at least
glance through, or use search, to find what you need in the following
umpteen million of screenfuls:

... * 1000000


===============================================================================================


Why doesn't Python do that?

We are not literally going to write text like that, but we did recently
re-organized the doc for one module specifically to put the most
commonly used stuff (about the 'convenience' functions) at the top
instead of buried where it was.

Quite simply, it's a lot more work: you have
to separate most useful parts from the rest, which involves judgement
calls and will cause some disagreement and ultimately won't be perfect.
Once done, two separate sections need to be mainained and kept in sync.

In the case above, there is no duplication to be kept in sync. More the
problem is that people working of the docs tend to either leave or move
on to code. Report like 'This section is unclear' are not too helpful
either.

 

[rh]

One week ago, "JoePie91" wrote a blog post challenging the Python
community and the state of Python documentation, titled:

"The Python documentation is bad, and you should feel bad".

http://joepie91.wordpress.com/2013/02/19/the-python-documentation-is-bad-
and-you-should-feel-bad/

It is valuable to contrast and compare the PHP and Python docs:

http://php.net/manual/en/index.php
http://www.python.org/doc/

FWIW, I refer to the docs often. I keep a local copy and
serve the pages up locally

1. http://docs.python.org/2/archives/python-2.7.3-docs-html.tar.bz2
2. unroll
3. cd python-2.7.3-docs-html
4. python -c 'import SimpleHTTPServer as foo;foo.test()' 9292
5. point browser to 0:9292

There's no doubt that one of PHP's strengths, perhaps its biggest
strength, is the good state of documentation. But should we feel bad
about Python's docs? I don't think that either the Python
documentation or community is as bad as JoePie91 suggests. (Well, I
won't speak for the people on Freenode's #python. It took me
approximately three minutes to be banned from there, with no warning
or explanation.)

Another response to the blog post, by one of the core developers:

http://blog.briancurtin.com/posts/why-i-dont-feel-so-bad.html

--

 

[Steven D'Aprano]

A problem that's majorly exacerbated by the myriad ways of doing some
things, with some of those ways deprecated and others theoretically
plausible but hopelessly impractical.

Here's an actual example that came up today at work. Suppose you have a
user-provided string that's supposed to contain a URL, and you need to
ensure that it doesn't have a trailing slash, so you can later add
"/foo" or "/bar". (Or alternatively, ensure that it DOES have a
trailing slash. Either works.) Start the timer, go find out how to do
it. Assume you are broadly familiar with PHP, and know how to do the
basics of string handling, and are competent at searching the web.
Ready? Go!

I'll wait for you to come back.

... Okay, some of you are back now. Just giving the stragglers time to
finish losing their marbles...

Alright. Here's what I found in a recreation of today's search. Google
search: php last character of string

http://php.net/manual/en/function.substr.php -- okay, so I can use
substr, but not string indexing, to find out what the last character is
-- "Returns the extracted part of string; or FALSE on failure, or an
empty string." What kind of failures result in FALSE, and what kind in
an empty string?

[snip]
The page http://php.net/manual/en/function.substr.php says:

Description
string substr ( string $string , int $start [, int $length ] )

OK. It then goes on to say:

Parameters
string
The input string. Must be one character or longer.

What? The input string can't be an empty string?

Huh, this is PHP. You're lucky it doesn't say:

"The input string. Must be one character or longer, except for the case-
insensitive string 'something-magical-happens-here'."

*wink*

 

[Mitya Sirenef]

Subject: Re: Do you feel bad because of the Python docs? To:
(e-mail address removed) Cc: Bcc:
-=-=-=-=-=-=-=-=-=# Don't remove this line #=-=-=-=-=-=-=-=-=- On

We are not literally going to write text like that, but we did
recently re-organized the doc for one module specifically to put the
most commonly used stuff (about the 'convenience' functions) at the
top instead of buried where it was.

Yes, I didn't mean it would be literally worded like that .

In the case above, there is no duplication to be kept in sync. More
the problem is that people working of the docs tend to either leave or
move on to code. Report like 'This section is unclear' are not too
helpful either.

I don't think that would work in the general case, for all modules,
because the 'inclusive' section should not be missing items that
logically belong there. For example, if I'm looking through string
formatting subsection, it would be confusing if some items were missing
because they were moved to the top together with other items from
different subsections.

In addition, the 'inclusive' section would have some advanced notes that
would not be included in the first section, even if items themselves may
be there.


For example, let's take timedelta section:

http://docs.python.org/2/library/datetime.html#timedelta-objects


At the end of this section there is a dozen lines of helpful examples.

I think vast majority of visitors need these examples (not a complete
list, just an example of examples), and it would be ideal if they were
shown at the very top of the page, without the need to scroll down:

.... print("It's been more than 10 days since %s" % old_date)
It's been more than 10 days since 2013-02-10 00:00:0031536000.0


(As a side note, I think it would be better if sections in datetime were
in separate pages, it would be easier to google and the navbar on the
left side is very crowded and rather hard to read - often I find myself
missing stuff that's in there and ending up just scrolling down through
the document until I find what I need -- it might be better if section
numbers were not included there, font for keywords was not fixed width
font, and topics didn't wrap so much - in case of datetime, all of the
topics have enough horizontal space not to wrap and yet 3 out of 7 do wrap!)


Of course, it can be argued that these are minor issues, that relevant
parts of documentation are still quite easy to get to, and if it takes a
few minutes longer, it's not the end of the world.

In my view, such small matters are more important than it looks, because
working on a project requires focus and if you spend just a few minutes
hunting around the doc pages, you start to lose the larger picture of
your design... I tend to remember the most important modules out of
standard lib because I've worked with them a lot in the last few years,
but I imagine it can be tough for people who program a bit as a hobby or
as a small part of their job.

I don't mean to say that Python docs are terrible, though. They're quite
good, especially as more examples were added in the last few years, but
if they were split up in the 95/5 fashion as I've described, that would
be pretty great.

-m

 

[Rick Johnson]

[...snip legit complaint...]

Have you opened an issue, or checked for existing issue? I would be open
to the idea that entries like that for int should not be overly type
specific and imply that the defaults are the only possibilities.

Terry (with all due respect), do you /really/ expect that people have the time to open an issue on the bug tracker? Do you really think that everyone who uses python even knows about the bug tracker? Do you really think that people will believe that their opinion is worthy of placing on the bug tracker? Do you really?

I think most will just end up ignoring the docs and either be forced to give up on Python or look for documentation elsewhere. Now, you could react tothat truth by saying:

"Well, who cares! The docs are the docs and if people can't grok them thentoo bad for them because i think they are awesome."

Sadly (in actuality) it's too bad for *you* Terry (along with the many other people who maintain docs) when you ignore the many request for changes. Remember, if people just ignore the docs because of these abominations you and everyone else are basically wasting your time maintaining the docs! Do you understand this fact?

Terry Implies: "We will write the docs how *we* see fit, and to hell with your feeble misunderstandings. You are beneath us! *We* are the anointed ones. *We* know everything!"

Look i know your intentions are noble, and yes my wording was a bit theatrically unfair, but this is /exactly/ how people are interpreting your intentions Terry. Please don't become a zealot. Python will never be perfect! I can assure you.

And besides, is a bug tracker /really/ the place to voice the many legitimate problems concerning python's documentation or stdlib? Forgive me, but I thought bug trackers where for tracking ,umm... well, BUGS!

This is why i mentioned the need for an official "PyWarts" (group or list) so these folks will have a platform to voice their frustrations. A very PUBLIC and very ACCESSIBLE and very WELL KNOWN platform. Because if IS NOT allthree of these things, then it IS nothing.

But you cannot just hand them a microphone and then stick your fingers in your ears. You need to /listen/ carefully and try to place yourself into their shoes. I can assure you that the Python docs, and the language itself, could use some polishing. Stop taking these complaints personally and start listening with an objective ear; please?

 

[Mitya Sirenef]

(As a side note, I think it would be better if sections in datetime were
in separate pages, it would be easier to google and the navbar on the
left side is very crowded and rather hard to read - often I find myself
missing stuff that's in there and ending up just scrolling down through
the document until I find what I need -- it might be better if section
numbers were not included there, font for keywords was not fixed width
font, and topics didn't wrap so much - in case of datetime, all of the
topics have enough horizontal space not to wrap and yet 3 out of 7 do

wrap!)

In regard to Python doc topic menu readability -- compare to the django
topic menu:

https://docs.djangoproject.com/en/dev/topics/db/queries/

It's ridiculous how much more readable it is, at least to my eyes!

-m

 

[Mark Lawrence]

One week ago, "JoePie91" wrote a blog post challenging the Python
community and the state of Python documentation, titled:

"The Python documentation is bad, and you should feel bad".

http://joepie91.wordpress.com/2013/02/19/the-python-documentation-is-bad-
and-you-should-feel-bad/

It is valuable to contrast and compare the PHP and Python docs:

http://php.net/manual/en/index.php
http://www.python.org/doc/

There's no doubt that one of PHP's strengths, perhaps its biggest
strength, is the good state of documentation. But should we feel bad
about Python's docs? I don't think that either the Python documentation
or community is as bad as JoePie91 suggests. (Well, I won't speak for the
people on Freenode's #python. It took me approximately three minutes to
be banned from there, with no warning or explanation.)

Another response to the blog post, by one of the core developers:

http://blog.briancurtin.com/posts/why-i-dont-feel-so-bad.html

Not really when we've got world leading experts to help us out
http://xahlee.info/perl-python/python_doc.html * sys.maxint

 

[Antoine Pitrou]

It is valuable to contrast and compare the PHP and Python docs:

http://php.net/manual/en/index.php
http://www.python.org/doc/

I suppose you should compare it with http://docs.python.org/3/ instead.

There's no doubt that one of PHP's strengths, perhaps its biggest
strength, is the good state of documentation.

My (probably outdated) experience with the PHP docs is that they are very
succinct and don't document failure cases or behavioral details at all.
Sure, if you only care about the big picture, they are good enough.

Regards

Antoine.

 

[Antoine Pitrou]

I think the issue with python documentation is that it ignores the 95/5
rule: 95% of people who land on a module's page are only looking for 5%
of its information.

The 95/5 rule is generally a fallacy which ignores that the 5% which the
readers are expecting to learn about is not the same 5% from reader to reader.
(*)

Which means that in the end you would really want a diversity of HOWTOs
targeted at different usages of the stdlib. But it is a lot of work to
write *and* maintain.

(*) cf. http://www.joelonsoftware.com/items/2006/12/09.html

Regards

Antoine.

 

[Mitya Sirenef]

The 95/5 rule is generally a fallacy which ignores that the 5% which the
readers are expecting to learn about is not the same 5% from reader to reader.
(*)

Which means that in the end you would really want a diversity of HOWTOs
targeted at different usages of the stdlib. But it is a lot of work to
write *and* maintain.

(*) cf. http://www.joelonsoftware.com/items/2006/12/09.html

Regards

Antoine.

It would be absurd on my part to claim that they're precisely the same
5%. But then again, they don't have to be. Consider that some topics are
covered in the official tutorial while others are omitted -- the authors
of the tutorial were following the same rough 95/5 concept and the idea
that some readers will find stuff they don't need in the tutorial while
at the same time not finding some of what they DO need -- did not stop
them from writing the tutorial, nor does it mean the tutorial is not
useful. -m

 

[Rick Johnson]

Which means that in the end you would really want a diversity of HOWTOs
targeted at different usages of the stdlib. But it is a lot of work to
write *and* maintain.

So instead we maintain a "simple", albeit broken, doc that experienced pythonista's prefer to read, whilst newbies loath? Is not the *target* audience noobs?

 

[rurpy]

One week ago, "JoePie91" wrote a blog post challenging the Python
community and the state of Python documentation, titled:

"The Python documentation is bad, and you should feel bad".

http://joepie91.wordpress.com/2013/02/19/the-python-documentation-is-bad-
and-you-should-feel-bad/

It is valuable to contrast and compare the PHP and Python docs:

tl;dr? tb

I haven't used PHP or its documentation so I can't compare it
to Python's. I have used Python's documentation and can say
I agree with many of the criticisms made by JoePie91.

One of the problems with "fixing" the Python reference docs
(by which I mean primarily the Language and Library References)
it that there is no common agreement about what a "good"
reference should be. In the Python development community
that controls the overall structure and contents of the
Python documentation, there seems to be strong minimalist
streak. It often seems like the documentation is the
product of a contest to find the minimum number of words to
describe something and still be able to defend it as correct.

Any documentation must be written with a target audience in
mind and IMO the audience for the Python reference docs should
be programmers familiar with one or two procedural or OO
languages at an intermediate level. (Obviously different
sections of documentation can modify this. Later documentation
will assume knowledge of basic concepts like Python objects,
argument passing and assignment semantics and so forth that
were presented earlier, and documentation for specialized
problem domain modules, eg an SMTP module, would assume some
knowledge of email, smtp and networking.)

As JoePie91 pointed out, reference material should describe
its subject matter completely and accurately. Once documentation
has archived that minimum bar of viability, its quality is
determined by how effectively it transfers that information
to the reader. I distinguish reference from tutorial material
in that the former is optimized for looking up information
and presenting it concisely, the latter for presenting (quite
possibly the same) information in a linear fashion with no
forward references and presenting it verbosely and experientially.
I distinguish a language reference from a language standard
in that the audience for the latter are language implementors
rather than users. I would describe a reference document for
those already competent with Python and as a big cheat-sheet.

A frequent failing of the Python docs is just plain poor
writing. When explaining something, start with a description
of what the something is, does, etc, in a form understandable
by the target audience. Is there anyone who can understand
what the very useful collections.defaultdict does without
multiple rereadings? According to its docs, it "returns a
new dictionary-like object." That is underspecified -- many
things return dictionary-like objects. It continues "it
overrides one method and adds one writable instance variable."
OK, but WTF does it *do*?! It then goes on to describe its
use which one has to understand without an overarching context
and then reason backwards to eventually figure out that it is
a dict that provides for user-specified behavior when accessed
with a key that doesn't exist [*1]

Important quality enablers are good tables of contents,
indexes, glossaries, cross references and examples.

Examples should be used to illustrate a textual description
and never used as a substitute for textual descriptions.

Cross references are particularly important in tying together
related material that is found in disparate doc locations.
For example, information on Python's "+" operator is found in:
Lang: 2.5. Operators
Lang: 3.3.7. Emulating numeric types
Lang: 6.5. Unary arithmetic and bitwise operations
Lang: 6.6. Binary arithmetic operations
Lang: 6.15. Summary (mislabeled, actually operator precedence)
Lib: 4.4. Numeric Types
Lib: 4.6.1. Common Sequence Operations
Lib: 10.3. operator
and probably other places I did not think to look.
The index is not much help in tying any of these together:
"add" -> Lib: 2.5
"+" -> Lib: 4.4
"plus" -> Lang: 6.5
There are also more obscure uses that should be findable such
as in float hex strings (4.4.3. Additional Methods on Float)

Cross references to similar information can help cover for
failings in the index -- if you can find some similar function
or concept, there is (or should be) a good chance of a cross-
reference to what you really wanted.

Good documentation will anticipate the questions a reader
will have and answer them.

----
Rebuttals to common responses to criticism of Python docs:

Python docs are already good
* Criticisms of Python's docs pop up on the Python
maillist and blogs with regularity.
* Many people confuse "usable", "i've learned to use
despite", "look impressive", etc with "good".

Google / blogs / stackoverflow / reddit, etc can provide better
* Even were it true, it is an argument that Python
doesn't need good documentation, rather than an argument
that Python's docs are good.
* They don't provide answers for infrequent questions.
* Answers can be conflicting, wrong, or out of date with
no way to correct.
* Even today, not everyone has access to internet all the
time.

Try it in an interactive Python session
* This is useful practical advice but experiments do
not substitute for documentation because they tell you
only what Python version 3.3 on Redhat Linux 4.2 does
on a machine with 2GB of memory 3 days after the full
moon.
Documentation is the ultimate authority for what it
is *supposed* to do.

Read the source code
* Oh please! The purpose of documentation is to alleviate
the need to read source code.
* Those most in need of documentation are those without
the Python knowledge to read the source code.
* Some source code is very complex and difficult to understand
even for experts.
* The behavior of source code is often obscured by details
not directly related to the info being looked for: error
handling, options for alternate behavior, performance
optimizations etc..

Don't complain, submit doc fixes.
* The people with motivation to fix the docs are often not
qualified to and the people qualified to have no motivation
because they already know it. (They may not even recognize
there is a problem.)
* There is a group of core developers who define (by accepting
or rejecting patches) the nature of the changes that can be
made. If the view of this group favors changes that continue
the status-quo, significant improvements via this route are
not possible.
* Small fixes can require orders of magnitude more effort to
submit and defend than the fix took to write.

Tutorials are the place to explain basics.
* Tutorials are great for some people but not everyone.
* They are not optimized for looking up and answering specific
questions.
* Their linear style builds on preceding info requiring
start-to-end reading.
* Since finding info in them is harder, there is an expectation
the reader will permanently commit the information to memory
as encountered. The best learning style for many is to
memorize most frequently needed info by looking things up as
needed.
* They often introduce programming or general programming
language concepts already known to the reader from prior
experience.
* They are often bloated with exercises/examples that are
not needed by readers with a higher level of experience.
* They require an unreasonable time/effort commitment for
those without a preexisting commitment to using Python.
* They are an alternate format of, not a replacement for,
information that should be in reference manuals.

The high standards demanded are impossible
* There are other reference manuals that do achieve a high
standard so it is not impossible, for example Beasley's
Python Essential Reference [*2]. The are also examples
for other languages.
* But, it may be impractical for the Python community
to achieve such results due to various Python intra-
community factors.

Python docs are excellent compared to most free software docs
* The "most free software docs" bar is too low to be a good
metric. Most such docs vary between "sucks" and "non-existent".
Please compare Python docs to best available docs (which is
why comparison to commercial books like Beasley's Essential
Reference is valid.)

----
[*1] I am not an advanced Python user nor a good technical
writer so my defauldict description may well be poor. That
does not mean that a better description than currently exists
can't or shouldn't be provided.

[*2] I am not holding up Beazley's book as a gold standard;
it has a number of its own problems. But it does provide
an example of reference material with better organization
and clarity than the python.org docs.

 

[alex23]

Terry (with all due respect), do you /really/ expect that people
have the time to open an issue on the bug tracker?

If someone can write a paragraph on their blog or this list
complaining about a problem, then yes, they have the time to open an
issue on the bug tracker.

This is the price of using open source software: you give back. You
don't get to say "I don't have the time for this, *someone else* fix
it". Who do you expect to give up *their* time to solve *your* issues?

Ranting on public forums is nothing but posturing at best, and at
worst an attempt to blackmail-by-shame people into doing something for
you. Same goes for calls for "the community" to "fix" things.

 

[Steven D'Aprano]

As JoePie91 pointed out, reference material should describe its subject
matter completely and accurately. Once documentation has archived that
minimum bar of viability, its quality is determined by how effectively
it transfers that information to the reader.

Those priorities are backwards.

Badly written reference materials that are ineffective at transferring
information is potentially useless, no matter how complete and accurate,
and there's often not much you can do to make it better written other
than throwing it away and starting again.

But well-written reference material that is incomplete can be
incrementally added to, eventually making it complete.

If anyone thinks that being complete is more important than being
readable, let me point out that the Python source code is a 100% complete
and accurate reference to the behaviour of Python. So we're done, yes?

No of course not.


[...]

Documentation is the ultimate authority for what it is *supposed* to do.

Incorrect. If that were true, then there could never be a documentation
bug. Documentation can be buggy, just as software can be buggy. If
function f() is documented as doing X, but actually does Y, which one is
correct? In general there is no way to tell. In practice, the ultimate
authority is the consensus (if any!) of the people who write the software.