On Tue, Feb 26, 2013 at 7:54 AM, Steven D'Aprano <steve+comp.lang.pyt...@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 -- http://mail.python.org/mailman/listinfo/python-list
