Do you feel bad because of the Python docs?

Discussion in 'Python' started by Steven D'Aprano, Feb 26, 2013.

  1. 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".

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

    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:
    Steven D'Aprano, Feb 26, 2013
    1. Advertisements

  2. There are some issues with the Googleability of the Python docs at the
    moment. It's much easier to find the official page of PHP's docs than
    Python's. Trouble is, the official page of PHP docs is a lot less
    helpful... like he says, it's in some cases flat-out wrong. And then
    you go read the comments underneath in the hope of learning what you
    need to know... and you find a pile of junk even worse than the main
    docs, but with the occasional useful gem so you can't dismiss it out
    of hand. (But it's buried among loads of code whose primary purpose is
    to explain why there's so much bad PHP code out there.)

    His "experiment" (name all the possible error conditions) is one that
    I guarantee you will fail in EVERY language. Even in Java, where a
    method has to declare every exception it might throw, makes an
    exception (if you'll excuse the pun) for "runtime errors"... such as
    division by zero. So if I write a function that takes two arguments,
    divides one by the other, and adds three, then I don't need to declare
    that it might bomb if you give it zero and zero. Will it be in the
    docs? Unlikely.

    The lack of examples is a valid concern. However, PHP isn't actually
    that much better, because the prolific examples don't always help.
    Examples are no panacea.

    Final point: "NO-ONE IS FIXING THIS". I wonder how many docs patches
    he's submitted, how many newbies he's courteously and competently

    The complaints about the community definitely do not apply to
    python-list. So I'd say that's a fairly good fallback: if you can't
    find what you need in the docs, and you've made a genuine effort to do
    so, ask on c.l.p/p-l and you'll likely get a response within a day -
    sometimes within the hour. (If Giacomo says he will respond within the
    hour, he will respond... within the hour!)

    tl;dr: Nothing's perfect but it ain't as bad as all tharrt.

    Chris Angelico, Feb 26, 2013
    1. Advertisements

  3. Steven D'Aprano

    Roy Smith Guest

    Having lived through a year of PHP hell, I've developed a theory about
    the PHP ecosystem (i.e. docs, forums, user community, etc) vs. the
    Python ecosystem.

    When people ask PHP questions, the questions tend to be phrased as "what
    do I type to get X", and the answers come back that way too. The forums
    are full of, "I had the same problem. Somebody told me to do this. I
    don't really understand it, but it worked for me and maybe it'll work
    for you too".

    The Python ecosystem is much more about understanding what's actually
    Roy Smith, Feb 26, 2013
  4. Steven D'Aprano

    Zero Piraeus Guest


    The Python docs are my first port of call when I know the module (and
    maybe the function) I want to use, but can't remember exactly how it
    works. For that, and for me, they're very good.

    I can also usually find the section I want if I'm answering a beginner
    question on Stack Overflow and want to provide an explanatory link,
    but if I weren't already familiar with the docs, I think it's quite
    unlikely I'd find the relevant page easily. I agree with joepie91 that
    the information on fundamental stuff is poorly organised.
    I think he has a point, albeit exaggerated, regarding the community -
    or at least python-list, which is the part with which I'm familiar.
    This list can be a little imposing for beginners, and its habit of
    veering away from the original question into an esoteric discussion of
    the language, while entertaining and educational to read for *me*,
    might well end up causing OP to scratch their head.

    I don't think it's intended, but sometimes there's also the sense that
    regulars here are trying, not entirely successfully, to hide their
    impatience with simple questions. I don't hang out at python-tutor, so
    maybe it's better there (in which case, maybe its existence needs to
    be better advertised).

    I think Stack Overflow is a little better at that, possibly because
    the rep system there encourages "grinding" in the MMORPG sense, and
    easy questions get a bunch of people piling on with answers almost

    Zero Piraeus, Feb 26, 2013
  5. 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
    -- 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?
    Comment on question: "There are more than 10 ways of doing this!"
    The accepted answer, fortunately, is a good one. Use rtrim. Okay.
    That's nice. But look at the other answers: one mentions substr (as
    above, that's half the question); one suggests the unwieldy form of
    indexing from the back (with an explicit strlen); one answers
    altogether the wrong question (suggesting the use of basename); and
    one... suggests a regular expression. Now you have two problems.

    And just to add to the pile of ways this could be done, the first
    response in this thread
    suggests *reversing the string* and indexing from the front.

    Maybe you tried different search terms and got better results, I don't
    know. This wasn't the only search I did in trying to find the best way
    to do this, but it was the one with the most amusing results.

    The original rant specifically excluded sites like Stack Overflow as
    valid sources, which in a way is fair enough. But it wasn't from that I got that information.

    Okay. Now I'll try it again, for Python.
    Google search: python last character of string
    First result:
    3.1.2 Strings
    Besides numbers, Python can also manipulate strings, which can be
    expressed ... word[-1] # The last character 'A' >>> word[-2] # The
    last-but-one character 'p' ...

    The use of code with directly connected comments means that I can read
    this part of the solution right there, without even clicking the link.
    Search Engine Optimization FTW.

    Searching for the second part, by adding the word 'remove' to the
    search, brings up more third-party sites - for PHP:
    and for Python:!topic/comp.lang.python/TIX5u3Zhikc

    In both cases, answering the question, but not from the language's own
    site. Forcing the matter with a site: search brings up poor results
    for both languages. Python gives me:
    but nothing about slicing. PHP: Take your pick of functions, and I
    hope you already know what they do, because the snippets don't help
    you choose:
    substr, rtrim, chop (which, once you go to the page, reveals itself to
    be an alias for rtrim), strrpos, substr_replace, strstr

    I'd have to say that, in the shoot-out, both languages died on their
    own merits, but stood on the merits of third-party support. Fifteen
    years ago, I would have called that a critical failure; in the 90s, I
    would search for information only from official sources. But these
    days, forum archives and blogs are some of the best way to find what
    you need - granted, Sturgeon's Law applies, but frankly that applies
    to a lot of documentation too (and Google's fairly good at helping you
    find the 10%).

    Chris Angelico, Feb 26, 2013
  6. Oooh, deja vu! It's like it's 1988 and I'm learning to program in
    Hypertalk all over again!
    Steven D'Aprano, Feb 26, 2013
  7. Steven D'Aprano

    notbob Guest

    Ahh! A point at which I can interject.

    As a rank green python noob, I definitely hava an opinion on python
    documentation and it's not entirely flattering. OTOH, it's hard to
    toss any other single linux based documentation up as a sterling
    example. IOW, I've seen worse. How am I learning about python?

    Several sources. The "Non-Programmer's Tutorial" docs from wikibooks
    was a false start. It goes for about 2 pages before I realized
    they've snuck in some python syntax without explaining it. So, I jump
    over to "The Python Tutorial", which immediately leaves me submerged,
    as it's waaay over my clueless head. I flounder around and
    desperately grab onto "Basic Python" over at Finally, I'm

    Whoda thunk it? I usta despise But, they've matured
    greatly since their early days. I'm not a programmer. In fact I
    really dislike programming. But, as a long time linux user, I really
    need to learn a useful higher language. And here is this website that
    takes me by the hand and speaks to me like what I am. Dumb as a post
    and disinterested. But, they are patient. They explain basic
    programming concepts before launching into specifics. When they do
    get specific, they use simple examples that make sense. The don't
    toss in syntax they haven't fully explained. Great site and the one
    I'm now using to progress. I'm sure the other sites I've named will
    become helpful, eventually, but now I can move forward with

    Are python doc sites perfect? No. I've yet to come upon anything
    that clarifies why's and wherefores and the differences between the CMI
    IDLE and the GUI IDLE. And boy, are they different! OTOH, as I said,
    I've seen worse Linux docs. BitchX or zsh? What docs!? Even the man
    pages took me a long time to figure out. Bluefish? Krita?
    Puh-leeze! emacs? It's a wonder I can use it at all. ;)

    Despite all that, I'd say python documentation is better than a poke
    in the eye with a sharp stick. I'm sure the official pages will make
    more sense to me when I understand more. As it is, they jes toss out
    "lc-letter" like I know what they're talking about. They explain it a
    little bit, but I still hadda wiki it to get the full story.

    As a person with some technical writing experience, I know how
    difficult it can be. I had to be careful about who I was writing for,
    engineers or laymen. It's the same with programming docs. Writing
    tutorials about python as if I jes came from 5 yrs as a C programmer
    is not in the least bit helpful to a beginner like myself. Sometimes,
    one jes hasta hunt for the right flavor.

    notbob, Feb 26, 2013
  8. Steven D'Aprano

    Adam W. Guest

    I think learning a language from the documentation is an unreasonable expectation and burden for the authors.

    Buy a book, take a class, they are designed to provide you with a path from start to finish in a sensible manner, the documentation in my opinion is supposed to be a reference and a refresher with an assumed level of basic fundamentals.

    I'm currently taking a class in ARM assembly, the notion that I should expect to plop the thousand+ page reference manual on my desk and just "get to it" is absurd.
    Adam W., Feb 26, 2013
  9. Steven D'Aprano

    Andrew Berg Guest

    Andrew Berg, Feb 26, 2013
  10. Steven D'Aprano

    MRAB Guest

    The page says:

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

    OK. It then goes on to say:

    The input string. Must be one character or longer.

    What? The input string can't be an empty string?
    MRAB, Feb 26, 2013
  11. Steven D'Aprano

    notbob Guest

    "This document was generated by Simon Ruderich on July 24, 2012"

    .....'bout damn time!! ;)

    notbob, Feb 26, 2013
  12. Steven D'Aprano

    Tim Chase Guest

    Tim Chase, Feb 26, 2013
  13. Steven D'Aprano

    notbob Guest various guises, dating back to the man pages. Not all as
    thorough as the latest "manual". Perhaps I shoulda qualified usable
    docs. ;)

    notbob, Feb 26, 2013
  14. Steven D'Aprano

    Terry Reedy Guest

    To me, this is a lying troll rant worth less than most of RantingRick's
    The contrast has been discussed before on python-list and even pydev. To
    repeat: in my opinion, and that of most core developers, the python docs
    are superior. It is Joe's lie to equate difference of opinion with

    Python has a nice Tutorial for beginners. It is an integral part of the
    doc set. To ignore that (and the indexes) in discussing the usability of
    Python docs by beginners is to lie. (If beginners who actually read the
    tutorial have problems with particular paragraphs, improvements can be
    and have been made.)

    Examples: Once startup is explained, the rest of the tutorial is about
    half text and half example. I think that is a good balance. Anyone who
    reads the tutorial knows how to call a function. I think doubling the
    size of the Library *Reference* with trivial, repetitive examples like:

    would be a negative for reference use*. Python has a super-duper
    interactive mode for trying things like this oneself, and that teaches
    *better* than just reading the same thing. (And if the tutorial never
    discusses len() and its generic use for all concrete collections, it

    * Anyone who disagrees can go to
    where you can find that and other examples for builtins and about 30
    modules. Actually, I can imagine that some beginners would benefit from
    this page as an extension of the tutorial. This site may be an outcome
    of the previous discussion, which more or less ended with the fact that
    anyone who wanted to produce php-style Python docs was free to do so.

    Searching: it is true that the Python docs are written for being read by
    people, rather than by search engines#. It has a hand-crafted index
    (yes, it still needs patches) that will get you most places, especially
    for anyone who has read the tutorial to get the basics. For 'length of a
    list' one can find 'len() (built-in function)' and find that 'len'
    indeed mean length and, more generally, size.

    # Anyone who wants to could develop an seo-optimized python-by-function
    website that goes into exquisite details for each function on a separate

    len(collection) => count
    Built-in function len() allows one to find the
    * length or size of a list
    * length or size of a tuple
    * length or size of an array
    * length or size of a string
    * length or size of a bytes
    * length or size of a bytearray
    * length or size of a memoryview
    * size of a set
    * size of a frozenset
    * size of a dict or dictionary
    * size of dict view
    * size of user-defined collecton class instances

    Returns 0 for empty collections. Raises TypeError for inputs that are
    not collections or that do not support len() calls, because they do not
    have a properly written .__len__ methods.

    If I were involved, I would *not* junk-up such pages with random user
    posts. Anything worth being added should be incorporated into the entry
    Terry Reedy, Feb 26, 2013
  15. That's how I learned it. The Python tutorial, together with the stdlib
    reference manual, are often recommended to beginners to Python in
    order to learn it. The combination of the documentation and consulting
    other programmers helped me learn the language just fine.
    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: .

    -- Devin
    Devin Jeanpierre, Feb 26, 2013

  16. 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? 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.
    It's important that they don't contradict each other.

    Right now places like SO and mailing list act like the first section I
    described. The issue is that they're not always up to date and not
    guaranteed to be correct, are not in a consistent style and depth, are
    not centralized.

    Mitya Sirenef, Feb 26, 2013
  17. Steven D'Aprano

    nn Guest

    For me on the other hand. The Python tutorial has been the most useful
    tutorial I have ever used. I had experience with Basic and Pascal.
    Most other tutorials go too slow for me and I loose interest. The
    python one just kept going and after reading the dozen pages in a
    couple of hours I had enough of an idea about the language to start
    doing the things I was interested in.

    The only thing that confused me at first was finding functions like
    "open" or "input" and string methods. I lost a bit of time searching
    in the language reference until I found out that they are in the
    Library reference: I didn't think of "open" as a library. But now I
    have no problem; all I need is found under Library reference in
    section 2 and 4 and starting with section 6. I also use the global
    module index when I already have an idea what I am looking for.

    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. As
    Einstein said:
    “Example isn't another way to teach, it is the only way to teach”
    Outside of the tutorial there are not a lot of succinct examples of
    more advanced uses of the different keywords and builtins. Thankfully
    for the libraries there is Python Module of the Week for people that
    know about it.
    nn, Feb 26, 2013
  18. Steven D'Aprano

    rh Guest

    No I do not feel bad.
    I did not read the post either.

    As a newcomer to python I found the docs to be difficult.
    I'm getting used to reading them after a few months.
    Any document is written for some audience, maybe
    python needs to target wider audience groups. One for programmers
    from other languages (maybe one for each major language?).
    One for those new to programming and python at the same time.
    One for python programmers (have mostly that now, I think)

    If I harken back to those days when I first used man pages
    it was a moment of "Wow! This is great!" followed by many
    moments of "Hmmmm, do they mean this...?".

    Incorrect docs are worse than none. I think most of the python docs
    I've read have been correct although sometimes stuff is just missing.
    Like threading.local was not easy to find.

    HTMLParser is avoided by lots of people because it requires lots
    of prior knowledge.

    Examples are worth more then plain old doc.
    rh, Feb 26, 2013
  19. Steven D'Aprano

    Rotwang Guest

    I strongly disagree with most of what the author writes. To start with,
    there's this:

    Let’s start out with a simple example. Say you are a developer that
    just started using PHP, and you want to know how to get the current
    length of an array. You fire up a browser and Google for “PHP array
    length site:php.netâ€. The first result is spot-on, and one minute
    later, you know that count($arr) will suffice.

    Now let’s say that you wish to do the same in Python. In this case,
    you would Google for “Python list length site:docs.python.orgâ€, and
    the first result is… a page with several chapters on standard types?

    It seems to me that this is /completely/ the wrong way for a developer
    who's new to Python to go about learning the language. If you don't know
    enough Python to be familiar with len(), the sensible thing to is not to
    try coding by finding out individual language features as and when you
    need them, but to read the tutorial, systematically from start to
    finish. This list is continually being bombarded with questions from
    people who tried the former only to become stuck when something didn't
    work the way they thought it should (I've been guilty of this too),
    because knowing vocabulary is not the same thing as knowing how a
    language works. The majority of such questions could have been answered
    by simply reading the tutorial. More still could be answered by reading
    the language reference, which really isn't very long.

    That's not to say that experienced users don't need to look things up,
    but then why would one restrict a web search to Almost
    every question I've had about how to do something in Python has already
    been asked at StackExchange, and Google will find it.

    When you Google for something, you will end up on a page that
    explains a lot of things, including what you’re looking for. But how
    are you supposed to know where on the page it is, or whether it’s
    even on the page at all? The problem here is that the particular
    operation you are trying to find documentation on, does not have its
    own page.

    And the solution is Ctrl-f.

    The general norm for the Python community appears to be that if you
    are not already familiar with the language, you do not deserve help.
    If you do something in a less-than-optimal way, other Python
    developers will shout about how horrible you are without bothering to
    explain much about what you did wrong. When you ask out of curiosity
    how a certain thing works, and that thing is considered a bad
    practice, you will get flamed like there’s no tomorrow – even if you
    had no intention of ever implementing it.

    This is not my experience at all. Even when asking questions that I
    could have answered myself if I had RTFM, I've received helpful advice
    and nothing that could be construed as a flame. I don't know how this
    compares to other programming language communities, but it's much
    friendlier to newcomers here than, say, sci.math (whose competent
    regulars are understandably suspicious of people asking idiotic
    questions, given how many of those people turn out to be cranks).

    PHP solves [ambiguity] by having examples for every single function
    and class. If you’re not sure what is meant with a certain sentence in
    the description, you just look at one of the included examples, and
    all ambiguity is removed. It’s immediately obvious how to use things.

    Python solves this by having an interactive interpreter. The tutorial
    goes to the trouble of pointing out that "t helps to have a Python
    interpreter handy for hands-on experience".

    If you are an experienced developer, then you are most likely in a
    very bad position to judge how beginner-friendly the documentation
    for a language is.


    Most of all, accept that your personal experiences with Python, as an
    experienced developer, are not worth very much. Listen to the newbies
    when they tell you the documentation is hard to read or find stuff in.

    But I'm not an experienced developer. I'm an amateur hobbyist who came
    to learn Python having only had any real programming experience with BBC
    BASIC and OPL (both as a child). I read the tutorial, then I read the
    language reference, now I'm reading the library reference. They're all fine.
    Rotwang, Feb 26, 2013
  20. Steven D'Aprano

    Jason Swails Guest

    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). It's worth pointing out that 'interpreter' appears in the
    original rant once (according to ctrl-F, whole thing was tl;dr):

    Want to know how the Python interpreter deals with input Y? Read the
    source. And so on, and so on.

    Not: "Open up an interpreter and input Y"

    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. (I recall
    one of RR's posts that actually had some good tips to

    Also, I'll bet the way I learned Python effectively would seem like
    nails-on-a-chalkboard to others -- and vice versa. The 'one-size-fits-all'
    doesn't work for documentation. Complete and concise often battle, with no
    clear winner.

    And his representation of the Python community does not appear to be
    representative of my experience (threads begun via trolling rants
    notwithstanding). But he's ranting on his blog; not a big deal really.

    Jason Swails, Feb 26, 2013
    1. Advertisements

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments (here). After that, you can post your question and our members will help you out.