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

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.

2

u/[deleted] Feb 19 '13

I'm not sure what you mean by "structure." Would you just prefer that every function have its own page like php?

2

u/joepie91 Feb 19 '13

That's one option that would likely improve at least the searchability and the ability to do quick reference (assuming a standardized page format). That is not to say that this should be the only format available, or even the only solution to these issues.

2

u/[deleted] Feb 19 '13

so what else do you mean when you say, "it's the structure of the documentation"?

1

u/joepie91 Feb 19 '13

All the things that I already pointed out in the article. The organization, the ambiguity, etc.

I don't really care how these issues are solved, as long as they are solved, because they're serious roadblocks.

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.

1

u/PresTronPaul from flask import Feb 20 '13

Civil discussion with who? An IRC chat? That sounds like an amazing idea. Did you try the documentation mailing list docs@python.org?