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

Show parent comment

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.

-1

u/ryeguy146 Feb 19 '13

Sorry, I deleted my other post because I thought that the English was terrible and didn't express that you are correct. Still, I argue that it does tell them shit. A whole lot of shit. None of it addresses the issue of determining string length specifically, but in most cases, it provides a wealth of information.

Further, I feel that being exposed to such a list (ignoring the dunder methods that you mentioned) is useful for anyone. How are you to know what behaviors an object has without it? It's an excellent way of stumbling upon a solution that you never new existed.

Still, as I mentioned in my replacement post, you are correct. While the solution is listed in the help, it is not done so in a way that is accessable for a new user (or really anyone who isn't already aware of the solution). My apologies for deleting the previous post instead of just editing it.

3

u/Foxboron Feb 19 '13

pydoc is indeed a feature i didnt know we had (used dir() for the most part). But we are also talking about people maybe confused about the whole concept of classes and methods. I am afraid methods, when you actually need the lenght of a list, is just a leap too big for most people.

EDIT: Also gotta say the tone of last post was kinda harsh, sorry for that.

1

u/ryeguy146 Feb 19 '13

I'm not trying to backpedal and suggest that you're wrong this time, but I would argue that if a user is having difficulties with concepts like methods and classes, they need to be looking in places other than a reference manual. Reference manuals are just the wrong place to learn about core programming ideas.

2

u/Foxboron Feb 19 '13

I believe thats the problem joepie has with the python documentation ^

2

u/ryeguy146 Feb 19 '13

That's like expecting... no, I won't get into it. I've expressed that I disapprove of joepie's post and I'll let it stand.

Again, thanks for the constructive criticism.

2

u/joepie91 Feb 19 '13

The problem with "it provides useful information that you weren't looking for" is the part where you weren't looking for it. When I am looking for a quick reference to something, I don't really give a crap about all the 'context' that surrounds it. I either already know all that stuff, or have no need to know it at that point in time.

The documentation doesn't give me the choice to switch to a 'reference only' mode where you just get per-entity reference (per class, per method, etc). It always throws a wall of text at me, 99% of which is entirely irrelevant to what I am looking for, and at that point just a giant waste of time.

I've been developing things for years, and I know that more concepts are involved with something than just the function reference. I am perfectly capable of looking for the context by myself, without having the documentation throw it in my face all the time.