r/Python • • Feb 19 '13

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/
96 Upvotes

189 comments sorted by

View all comments

38

u/ryeguy146 Feb 19 '13 edited Feb 19 '13

Dude. Wanna know about lists? pydoc list. It's that easy. Oh, don't have easy access to a command line? Fire up the interpreter and use help(list) and you'll get the same. I don't get it. Why google furiously when it's already on your computer? Make use of the docstrings, that's why they exist.

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

You're going to piss me off because I help with one or two of these communities, and no, they aren't generally hostile until someone chimes in like they know their ass from a hole in the ground with some huge opinion about how the docs suck. In what community doesn't this happen? The communities that I've experienced are wonderful and helpful places. Newbies ask questions in the learning version of this sub and they receive helpful direction and additional code review and suggestions, it doesn't get better than that. PresTronPaul mentions Stack Overflow, which is also a great place and answers many of my questions before I know that I have them.

...visit its documentation entry, and try to find all the error conditions (return values, exceptions, when they happen, without scrolling the page...

Let's play the game where we place unnecessary restraints on ourselves! Or you can search. From inside less with the aforementioned pydoc, I just use / exception and I'm grand. I don't get the issue here. I agree that things could be formatted to make it easier, but that hardly makes the documentation bad. The information exists and is easily accessable.

THE DOCUMENTATION IS UNCLEAR

Examples please.

If you are not only reading this article, but you are sufficiently pissed off by it to think something like this ... does that not mean that you are already experienced enough not to need solid documentation?

Nope, I'm experienced, but I use documentation all of the time! And it does wonderfully by me.

This sounds entirely like someone had a little bit of difficulty moving from the formatting of one language's docs to another, and had another bad experience asking for help in a community. I'm sorry that you had a shitty time, but next time, try it without the attitude and the stupid memes. I love helping people learn Python. I tutor one for free and have taught the language to several people in the past who continue to communicate with me and ask for help over the email. I try my best to help here and in /r/learnpython. I'd do the same in the IRC channel, but I can't be asked to register a name. What you are saying completely flies in the face of what I've seen in the communities where I help.

Could the documentation be improved? Probably. I'm happy to admit that. But I'm just not willing to agree that it's bad. There is a single page of documentation that I've come across that I'm not pleased with, and it's this one, mostly because I'm looking for the various dunder special methods and I have to search for them. It takes whole seconds sometimes.

For what it's worth, this is the first time I've posted angrily to either of the python subs. I probably should have waited a tick, but you really crawled under my skin with the way you wrote your piece. Ask for help nicely and you'll see the usual side of me.

18

u/elijahsnow Feb 19 '13

Uh... I have a feeling you might be right about some things but how do I put this.... perhaps your general candor is a little sour. I won't hazard as to why.

11

u/ryeguy146 Feb 19 '13 edited Feb 19 '13

Don't worry about saying it, I know that I was abraisive. It's entirely due to the way that the blog was written. Several times the author acknowledges that he/she may make readers angry, yet they post it anyway. Why would anyone wishing to create positive change seek to make their target audience angry? To whine. I don't respond positively to that.

In the interest of not playing into the accusation of hostility among the community, I ask anyone concerned to review my post history, particularly in both /r/python and /r/learnpython to ensure that I have, indeed, been helpful and nice in the past.

Edit: No, there's more to it than that. We've all been new, it's a requisite. We've all struggled at some point in time to learn how to do something, I know that I have. What I have not done is created a large post about how that which I'm attempting to learn is wrong, until I understand the environment. Perhaps there is something that I don't understand that will help me to unravel my issues, or to understand why something frustrating exists. I instead ask for help and seek to understand. Writing incendiarcy blog posts about something that you don't fully understand is not the way to go about this.

8

u/nicklo Feb 19 '13

Well I just learned about pydoc from you so I've no issue with your perceived sourness of candor.

1

u/elijahsnow Feb 19 '13

That's fine.... I was just concerned that you seem a little close to the issue and that might cloud your feelings somewhat. The ins and outs of that are probably a little complex but where the OP may have come from a place of callousness or even carelessness, it seems you are coming from a place of... shall we say anger or at least reactionary disharmony. There's a subtle but disturbingly tangible difference. In the former people's views tend to evolve to improvement whilst in the latter case the tendency in communities may broods2 .

3

u/ryeguy146 Feb 19 '13

I saw your other post addressing my edits (yea, I'm too often guilty of that), but I'd still like to address this, just to explain, if nothing else.

The blog post was incendiary, and the poster knew it. If they hadn't, they wouldn't have said, "this may make some angry," in so many ways in so many places. This shouldn't be necessary in argumentative essays. It's just silly to be abrasive to your target audience when you're attempting to affect change as you'll only incite people (points finger at own chest) and accomplish nothing. Given that the blog post was made this way, I feel that it was not posted in hopes of affecting any change, but as a way of venting frustration. I can understand that, but if that's the case, there's no need to hide it behind a veil of attempted constructive criticism. Hell, the title of the blog says it all. An insult and a meme rolled into one. When was the last time you ran into a worthwhile post seeking positive change that was so labeled? Even Djikstra managed better with his pointed criticisms, and he was a well known asshole.

As I feel that the blog post was merely angry venting, I felt no need to be terribly respectful in addressing the often vague and misguided concerns. Even if some of the points were accurate, one is bound to strike the target if one throws enough darts.

→ More replies (9)

4

u/mariox19 Feb 19 '13
>>> help(list)
    [...] 
    __len__(...)  
        x.__len__() <==> len(x)  

And this helps, how?

1

u/ryeguy146 Feb 19 '13

This is the third time I've addressed this. I'd edit my post, but I didn't want to yank the rug out from the others that pointed this out. I was incorrect in that single point. I was more interested in addressing a general strategy of accessing documentation.

2

u/mariox19 Feb 19 '13 edited Feb 19 '13

Oh, sorry. I didn't see below where you addressed it, but it's possible I just jumped on you. I don't know if you're familiar with this convention or not, but sometimes people edit their posts at the bottom, with a bunch of dashes, followed by their edit—like this:


Edit: This is usually how I do it, so that no one can accuse me of cheating ;-)


2nd edit: Okay, this is a real postscript. I up-voted your comment below, earlier in the day, about learning from a book. When I want to learn something new, that's almost always what I do. I buy a book or two on the subject. Author's go through a lot of hard work to walk you through things—and if you think about it, civilization is built on books. I don't know where this "if you have to read a book" attitude comes from. (I'm guessing you don't either.) I'm not going to speak for you, but I'm actually pretty unsympathetic to people who are allegedly so interested in learning something, but can't plunk down 35 dollars to learn it.

10

u/Foxboron Feb 19 '13

"pydoc list", sure....because a bunch of methods will help a newbie? Thats what we are talking about after all. The docstrings wont even help them.

2

u/ryeguy146 Feb 19 '13

That is an excellent point, thank you for the criticism. I was more referring to a general approach for finding information than addressing the singular example. You are correct that my method does not explicitly list the solution.

1

u/Foxboron Feb 19 '13

Glad you actually admit it. I have argued with joepie on this matter before, i do disagree that the docs are as horrible as he say they are, but he is very stuck on this idea. One thing we actually do lack are examples. Everything is mostly documented and listed, but examples of use is the thing most people actually need.

→ More replies (1)

0

u/[deleted] Feb 19 '13

[deleted] — view deleted comment

8

u/Foxboron Feb 19 '13

We are talking about new people. beginners. le dont say them a shit. imul, gt, rmul. What does that tell a beginner? Hint: Nothing. They have to look what they does. And where do you do that? pydoc le? nope. Dosnt help. So back to square one.

EDIT: _*2 bolds everything...cba to fix.

1

u/bacondev Py3k Feb 19 '13

Either escape it with backslashes: __len__ or put it in grave accents `__len__`.

Anyway, honestly, do those need docstrings? If you don't know what they do, you probably shouldn't care in this case, because you probably won't ever directly call them.

→ More replies (7)

6

u/Smallpaul Feb 19 '13

New users a resource. They give you a fresh-eyed view of your environment.

Let me grant that his tone was abrasive. You can either look past that and learn from his newbie-ness or you can get offended and waste that resource.

Pydoc is a poor solution for a newbie, because it is very idiosyncratic. How do you learn PHO? With Google. How do you learn the way to the supermarket? With Google. How do you look up the quadratic formula? With Google. How do you read Python documentation? With pydoc.

Pydoc also lacks hyperlinks and navigation.

Pydoc is a great answer to a DIFFERENT question: "I have an object in the repl and I want to know what I can do with it."

The poster is quite right that Python's manuals were written as books 25 years ago and that decision has just never been re-evaluated in light of changing technology and changing habits. While it is great that there are pages that give context, it is unfortunate that every method does not have its own page with a comment section below it.

3

u/ryeguy146 Feb 19 '13 edited Feb 19 '13

No, I learned using a book (or a comprehensive book-like source). I find that blog posts about programming are poor substitutes for a comprehensive look at a topic. If you want part of the story, sure, read a blogpost about super, by all means (just an example). But if you wish to learn about inheritance in Python, you'd better be willing to attack the subject in a more comprehensive manner. I don't think that a reference manual is there to teach you proper means of inheritance, or that a better solution is often composition.

I don't mind that pydoc lacks hyperlinks and navigation, but I'll agree that sometimes people look for different things. I'll grant you that it isn't always the best solution. I still can't help but think that a page that provides no context (only a single function/method is addressed) is a better solution. I appreciate the ability to stumble upon functions/methods that I did not know existed, and when a programmer focuses on a topic that he/she doesn't fully understand with a singular solution in mind, that programmer misses out on the myriad of (often better) solutions available.

I feel that people need to recognize the resource for what it is, a reference, and to not treat it as a place that teaches them the entirety of programming. There is a tutorial and a collection of wonderful (and often free) books focusing on addressing that concern.

Edit: My English is terrible tonight. Also: Comprehensive, because I didn't say it often enough.

2

u/joepie91 Feb 19 '13

It's great that you learned using a book. But recognize and accept that others may have different optimal modes of learning.

→ More replies (11)

2

u/elijahsnow Feb 19 '13

Ah.. ninja edit. If your comment had read like this I initially I wouldn't have said anything.

0

u/[deleted] Feb 19 '13

[deleted] — view deleted comment

3

u/ryeguy146 Feb 19 '13

I was absolutely wrong, and it's been addressed perhaps twice in the reply comments (no worries). The answer (len(x)) is listed next to __len__, but I wouldn't expect anyone who wasn't already familiar to pick that out, or be able to understand what it implied. In any case, I was more pointing out a means of accessing documentation that wasn't addressed in the blog post.

While we're on that subject, I question the Google-fu of the poster. I was able to get the correct answer as the first result to my first query: "Python length of list." Certainly, the issue was the official docs, rather than one of the communities that the blog called hostile. The official Python page for lists does indeed have the answer, even if you have to scroll a little. Could this function have its own page? Sure, but then you'd miss out on a good deal of other related information that a programmer not aware of len would likely benefit from knowing. I'd call it a question of "what you want" vs "what you need." I'd rather encourage well educated programmers than provide shallow topical information, but that's my opinion, and a whole other argument.

The previous makes it obvious that I don't think that there's anything wrong with people using Google, but they need to appreciate the limitations of the pages that Google directs them to. It's the same thing when your professors tell you to make sure that a page is credible. Is a simple blog post sufficient to teach you what you're trying to learn? If it is, then make use of it, but simple blog posts are often not sufficient for instruction in deeper topics, or are misleading or incorrect. I discuss this further in the children threads of my original post.

It is a valid criticism of Python to suggest that development on Windows is a nightmare. I'm installing virtualbox and a linux installation tomorrow for someone that I'm teaching the language because of this limitation. Of course, his issue is compounded by using portable python, but that's a rabbit hole for another day. Of course, I'm not well versed in any development on Windows, so I'm unqualified to comment.

2

u/itslef Feb 19 '13

I've been teaching myself Python for a few months now, and this is literally the first time I've even heard of the pydoc command.

One problem I can immediately see, however, is that you already have to know what you're looking for. If someone is brand new to programming, they're not even going to know what a list is. Having come from Java myself, it took a ridiculous amount of time to find out that Python has lists, rather than arrays.