1. 29

  2. 14

    Man, 6 years and nothing has changed. PHP still has a simple page for just that function [1], and Python still has that megapage [2]. Granted, so do other languages like Ruby [3], but JavaScript has a similar style [4] as PHP.

    PHP style is just better in my opinion. Its gives you room to expand the docs as needed. Each function page can have a function prototype, examples, See Also and comments. Also, Python sometimes wont tell you the expected type of the inputs [5], or the outputs [2]. You can infer them in many cases, but in others you basically have trial and error.

    1. https://php.net/function.count
    2. https://docs.python.org/library/functions#len
    3. https://ruby-doc.org/core/Array.html#method-i-length
    4. https://developer.mozilla.org/Web/JavaScript/Reference/Global_Objects/Array/length
    5. https://docs.python.org/library/datetime#datetime.datetime.utcfromtimestamp
    1. 6

      Yeah, that PHP documentation is orders of magnitude better than Python. Python documentation is pretty painful to use, in my experience.

      I really like Rust’s documentation: https://doc.rust-lang.org/std/vec/struct.Vec.html#method.len

      I also like that each struct, function, etc. links to the source code.

      1. 3

        I can second (or, I suppose, third) this. I have almost stopped clicking python documentation links when I’m looking for how to do something with python, which isn’t great.

        And yeah, Rust’s documentation is great. I don’t write much Rust, but I always end up on Rust documentation pages when looking for details on Wayland protocols, because documentations for the Rust bindings seems to be almost all there is of Wayland protocol documentation other than the protocol XML files themselves.

      2. 3

        I worked professionally with PHP for some years, and the docs was either very good or very obscure. I remember when I had too look at the comments written by other programmers to find relevant examples and explanations.

        I don’t particularly dislike PHP, but the docs was one of the reasons for which I chose not to proceed with PHP later in my career.

      3. 8

        It embarrasses me to admit this, but Python is the only language I use professionally in which I find myself opening files irrelevant to what I’m working on to copy & paste from the last time I figured out how to call a function. Sure, the official documentation is impenetrable, but that pales in comparison to my daily experience of quick-viewing a function signature only to be greeted by something like:

        apply_function(a, b, key=False, type='default', *args, **kwargs)

        1. 7

          I find pymotw much more succint and helpful 90% of the time since I need an integrative example and not just the individual parts. I need help in understanding how they go together.

          Agreed that the Python documentation could improve in a variety of ways. We need:

          • An API level reference that describes the stdlib in things like arity, types, and what the methods / classes do and are for.

          • random.choice for example, should link to what seq is. Overall, this method pretty much fits the bill.

          • A set of examples of how to use the specific methods that are found in a given package.

          • This could show something like.

          random.choice([1,2,3]) # 2
          • I think each method should have an example, no matter how simple, full stop.

          • A higher set of narrative examples at the package level that how to use it to solve problems. Sometimes these are called examples and recipes.

          • This should be a further expanded and solicit for examples, similar to what this is trying to do: https://docs.python.org/3/library/random.html#examples-and-recipes

          • A package that I found originally incredibly unhelpful was asyncio. It is notoriously hard to grok without these kinds of examples. I’m not sure if things have improved since I first looked a couple years ago.

          I will no doubt piss off quite a few people with this statement, but the community around Python is one of the most hostile and unhelpful communities around any programming-related topic that I have ever seen - and with that I am not just referring to #python on Freenode, but to communities with a dense population of Python developers in general. This point actually consists of several separate attitudes and issues.

          I also cannot disagree with this more. The Python community has been fantastic in my experience. After nearly a decade and having been formerly a Developer Evangelist where I attended dozens and dozens of conferences, PyCon is still my favorite conference for the things I’m able to pick up and learn, the culture, and the inclusivity.

          1. 2

            FYI your link to pymotw is “lhttps://pymotw.com/3/” (note the preceding ‘l’ ‘https’)

            1. 1

              Thank you! Fixed.

          2. 3

            Holy crap this is true. I very vehemently dislike PHP but always found what I needed in its documentation, and readily found usage examples.

            Python is my language of choice, but both the language docs and docs from the community tend towards being very incomplete and have very few solid examples.

            Take argparse for example. The documentation page for it is LONG, and complicated, but actually does a rather poor job at explaining how to actually use the thing. Witness the 5 argparse tutorials out there on the web that try to get people started in a reasonable way.

            It’s a shame, really. Python is easy to learn as a language and really is a great starter platform, but the entire community needs to embrace the importance of truly superlative docs.

              1. 1

                I mean, there are a zillion things that do a different / better? job at handling argument parsing. Here are a few:



                The list goes on and on.

                It’s not that we’re stuck with argparse, it’s that argparse’s documentation is actively user hostile and people end up turning to alternatives when argparse would probably work just fine a lot of the time.

            1. 3

              I agree it’s not great, for instance what exceptions get triggered is 99% missing from the docs. But I don’t see many patches being sent in…. that’s on me as well, Next time I have to look up a function in the docs, I’ll try to send in a patch that makes it better at least.

              1. 3

                The community is generally unhelpful and hostile (save for Reddit and SO, generally). Beginners are often treated as unworthy of help.

                Compared to what exactly? I’ve used multiple languages and in my opinion, python community is among the more friendly and actually helpful most of the time.

                1. 1

                  The author seems to have updated their post, but not actually made it any clearer what the issues were. My experience is like yours. [Update: I found http://cryto.net/~joepie91/manual.html based on a search. Therefore, I’d suggest the author’s experience is unsurprising, if that is indeed the approach.]

                  I have seen people fail to understand any of the history or context behind how we end up with the current state of Python. They’ll typically attack the GIL, or some other aspect of the language which Pythonistas already understand is less than optimal. In my experience, Pythonistas tend to be very pragmatic and want to get on with what they are building versus engage in these conversations. In response they get treated like “they aren’t even smart enough to know what is wrong with their language”. This is infrequent in Python communities, but Smart Aleck’s try it from time to time. It’s almost the first post on Hacker News.

                2. 2

                  I proposed an improvement for this in 2014: https://groups.google.com/forum/#!topic/python-ideas/cNNVYkyEtWQ

                  Sadly got nowhere.

                  1. 1

                    That’s unfortunate. Thank you for the proposal. I wish the article was better received - as a call to action.

                  2. 2

                    If you think Python’s docs are bad, then Ruby’s docs are appalling. When switching from Ruby to Python for some projects I’m happy to have better docs for a change.

                    1. 2

                      Working on PHP documentation was a great way for me to meet people and help me grow my career, way back then (a decade before this article was written). I take a small amount of credit for making/keeping the docs great during that time.

                      I eventually moved on from PHP for the most part, but I still have friendships formed, and colleagues I aligned with, during that time.

                      1. 1

                        My biggest gripe with the Python docs is that they list the versions that introduced a function or method at the end of whatever block of text talks about them. I very regularly look up the datetime documentation and try to use fromisoformat() in Python 3.6, which then blows up at runtime. Grrr.

                        1. -5

                          Upvote Just because Sven (joepie91) is a nice knowledgeable guy. I know him and look up to his level of coding.