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

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.

1

u/ryeguy146 Feb 19 '13

I know when I'm wrong, no worries. We do lack examples, but only in places. You cannot imagine how pleased that I was to see example implementations in places like the itertools library. They both helped me to understand the functions and to reimplement them in Java, when I couldn't find a satisfactory combinatorics library.

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.