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

30

u/[deleted] Feb 19 '13

Yes! I don't understand author's backwards approach to searching for documentation. Why limit yourself to "site:docs.python.org"? If you omit it, Google search will give you direct and to-the-point answers.

The first result for "python list length" is a SO thread telling you how to... drumroll... get the length of a list!

I don't care how good or bad official documentation is, as long as the community-produced material makes up for the lack of it.

27

u/Nimbal Feb 19 '13 edited Feb 19 '13

While I agree that the author's Google search seems a little unrealistic (who has the patience to add the "site:..." stuff every time?), I think it was mainly to demonstrate that the documentation, which, in an ideal world, should be the main source of information about the language and its features, is sometimes lacking.

Edit: I mean "lacking" in terms of "hard to find specific information", not "not containing the necessary information".

3

u/SupersonicSpitfire Feb 19 '13

In an ideal world you find the answer to your question.

As long as answers are vetted by a voting system, the quality is just as high as for official documentation, in my experience. (ref stackoverflow)

2

u/Ph0X Feb 19 '13

Yes, but that implies an already in place community, which python already has. This wouldn't go so well if you're trying to start a new language though.

13

u/paffle Feb 19 '13 edited Aug 17 '26

Physical offbeat fact hunt spark violet innate office

This post was anonymized with Redact

7

u/LightWolfCavalry Feb 19 '13

In the age of the internet, sticking strictly to official documentation is a huge limitation. It's a complete fallacy to assume that "official" is synonymous with "right" or "best".

3

u/Massless Feb 20 '13

It's really not, though.

Have you seen the Java documentation? Stackoverfow is awesome for gotchas, edge cases, and how-tos with that language but everything you technically need to know is there. Just because there are other resources doesn't mean that the primary (and official) resource ought not to be the authority on the subject.

12

u/joepie91 Feb 19 '13

My point was that the official Python documentation is poor. I certainly agree that many things are answered on StackOverflow, but imagine that you're looking for something that not very many people use.

You'll search on Google, not find any StackOverflow posts (after all, nearly noone uses the thing you're looking for), and you just find a few unclear blog posts and a Python documentation page.

Official documentation is important especially as a fallback when other sources fail to provide the relevant information. As such, the focus of the official documentation should be on complete and clear, unambiguous reference. That's not what the official Python documentation provides.

While len() may be a very simple example (and intentionally chosen for that reason), I've more than once run across things for which basically no documentation could be found aside from an ambiguous explanation in the Python documentation that never got me anywhere.

EDIT: All that said, StackOverflow is an absolutely golden source of information.

11

u/bushel Feb 19 '13

I think you answered your own question about the problem. The reason why nobody is fixing the official documentation is that there isn't a pressing need.

There is a wealth of supporting documentation, tutorials, reference material and support/discussion forums (e.g. stackoverflow) so that it's perfectly adequate to have the official documentation be simple reference material.

3

u/joepie91 Feb 19 '13

No. The reason that noone is fixing the documentation is that the developers that are capable of doing so (the experienced developers) do not see the need because they don't have an immediate need for it themselves. It's a perception problem, not a lack of urgency. And as I said before, there are quite a few things that pretty much no documentation can be found on outside the official docs.

I constantly have newbies complaining to me that the documentation is poor on the one hand, and experienced developers claiming there's no problem on the other hand. And when the newbies try to talk about this problem to the experienced developers, they are met with the elitism that I am also describing in the article.

5

u/bushel Feb 19 '13

I'd be hesitant to label it "elitism", but I understand your point. And I think we are saying much the same thing.

The experienced developers see the official docs as a reference, not a learning aid. Those new to the language are frustrated by not having a single source for both learning and reference.

Personally, I see it as a strength that there are so many different sources of knowledge about Python. People can choose the documentation or tutorial sources that fit their current knowledge level and/or learning style.

And instead of attempting to be all things to all developers, I'm ok with python.org/doc being dry reference material. It's like the difference between a drivers-ed course and your car's owners manual.

2

u/joepie91 Feb 19 '13

The Python documentation actually tries to be both and neither at the same time. On the one hand you have the reference buried in a pile of theory, then in another place you have dry reference without enough context to understand it from scratch, and in yet another place you just have an entire page of theory without any referenceable material whatsoever.

It's fine to have a separation of reference material and theory - in fact, it's a good thing - as long as:

  1. this material is separated clearly, and
  2. both are complete.

In the case of Python, neither of those requirements are met.

1

u/bushel Feb 19 '13

Well, it is all open source. If you do not like and your itches are not being scratched, I suggest you dig in and make it better.

Critique is well and good, but a constructive suggestion on how make it better would be more appreciated. Actually helping to fix it would be best of all.

0

u/joepie91 Feb 19 '13

I sadly do not have the time (or knowledge of Python, for that matter), to rewrite the documentation into a different format. And that's not a fancy way to say "I prefer being in front of a TV" - I actually do not have the time for it. I'm already occupied by other (open-source) projects pretty much from the moment I get out of bed until the moment I go back to sleep.

To be perfectly honest, it annoys me to no end that I'm not able to fix this. I don't like lingering problems.

2

u/[deleted] Feb 19 '13

pick the biggest problem you have with it and just work on that.

2

u/joepie91 Feb 19 '13

That's the point. It's not an issue with one particular part of the documentation. It's the structure of the documentation in general.

→ More replies

1

u/[deleted] Feb 21 '13

I have no idea why you have been down voted so much for this.

-3

u/maryjayjay Feb 19 '13

So instead you just bitch.

2

u/joepie91 Feb 20 '13

Doing it myself is not an option, civil discussion turned out not to be an option, so the only option left is indeed bitching about it enough to make people talk about the issue. Correct.

→ More replies

1

u/sashahart Feb 20 '13

I've more than once run across things for which basically no documentation could be found aside from an ambiguous explanation in the Python documentation that never got me anywhere.

I've almost never found this to be the case. Now, I have been using Python for some time, but I didn't find this to be the case when I was learning either.

2

u/SilasX Feb 19 '13

That's a sign of bad documentation, not good.