Do you feel bad because of the Python docs?

[Devin Jeanpierre]

On Tue, Feb 26, 2013 at 7:54 AM, Steven D'Aprano
<steve+comp.lang.python at pearwood.info> wrote:
> 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.

Who's we? As a user of Python I feel no responsibility for the state
of Python's documentation ;)

Do I feel like it could be improved? Sure. I've never understood why
Python doesn't document information about possible errors inside the
function documentations. Instead, you have to read the exception
documentation to find out when it might be raised, and then the exact
error conditions aren't always clearly specified at all.

My understanding from talking to members of the development team has
been that this is by design, so I've of course never submitted a
patch.

> (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.)

I'm an op in #python. If you can provide logs or a nickname I could
look into this with whoever banned you (if the ban hasn't expired
already!) However, you should appreciate that, having only been there
for three minutes, you may not have understood the expectations
#python sets on tone or subject matter. It is markedly more strict
than comp.lang.python. Also, bans aren't explained (except possibly in
the kickban message, but that's rare) unless you ask about them. It's
very easy to infer a reason from context, explanations take time (if
you explain before the ban), and PMs to a just-banned person never go
well (if you explain after the ban).


As to whether or not JoePie91's observations are correct for
#python... all the observations would apply to #python except for the
ostrich and source-reading complaints, albeit viewed through a very
negative light. I would disagree with his explanations for the reasons
for things, and his ranking of the importance of things.

IMHO the most important flaw in #python is that it's unwelcoming to
new programmers, but I can't think of a decent way to fix that.
Tutoring new programmers takes a huge amount of time. At the moment I
figure that the best we can hope to do is identify them before we
confuse the hell out of them by telling them to use classes,
generators, higher order functions, and other intermediate to advanced
topics. Unfortunately, we're not good at this. (Yet? :)


By the way, interestingly enough, JoePie91 was in #python discussing
his blog post for a bit. It was a fun conversation.

-- Devin