Hacker News Reader

Comment by michaelfairley | Hacker News Reader

Python docs aggravate me in numerous ways. One main complaint is that there is a single page[1] for all of the standards types (boolean, string, list, dictionary, numbers, etc.) that contains way too much disjointed information. It could really stand to be split into a few different pages, as it's annoying that Googling "python string", "python list", python int", etc. all lead to top of the same exact page.

[1] http://docs.python.org/library/stdtypes.html

View on HN

Compare that with this: http://ruby-doc.org/ruby-1.9/index.html

I find that page (docs.python.org) easy to navigate using the side menu and the structure of the document the fact that it is so big doesn't quite bother me, I already know most of what I need on that page and wouldn't be upset navigating it if I had to.

"Compare that with this: http://ruby-doc.org/ruby-1.9/index.html

I have on my recklessly large to-do list plans to update the API docs on ruby-doc.org with YARD.

The template seems a bit easier to navigate and the overall results better. But I'm always open to concrete suggestions.

[note: I run ruby-doc.org]

I in no way said that the python docs were worse than the ruby ones, only that the python docs are really not as great as they could be. You already knowing everything on the page doesn't make it any less poorly designed. I find it much more preferable to be able to search for "python string" on Google and be brought straight to a page about strings, not about every type in the languages (Ruby[1] and Java[2] both do this sanely.)

The formatting within the python docs is also highly inconsistent. Why (on the built-in types page) do the operations on sequence types (5.6) get a nice table, but the operations on sets (5.7) have a poorly formatted list?

[1] http://ruby-doc.org/core/classes/String.html

[2] http://cupi2.uniandes.edu.co/site/images/recursos/javadoc/j2...

As a very occasional Python user, it was very informative for me to see that String is a Sequence type. That immediately tells me something very important about Python, that I might be able to use similar functions and methods on lists, tuples, etc.

It's this comprehensiveness of the documentation that has impressed me before when I've needed to look things up about Python, and was enlightened about things I didn't expect to be.

I agree that all of that needs to be made clear in the documentation, but that need doesn't directly entail everything being on one page. What if the string page noted at the top that was inherited from the sequence type, or displayed sequence's methods as well as string's methods, and noted that they there are from sequence?

If I remember that correctly, the 'one page' style of python documentation came only in rather recently (last couple of years, >2.3), and the previous style was split one many pages: http://docs.python.org/release/2.3.5/lib/module-string.html

Back then I always hoped for the single page, because I was beginning with the language and jumping up and down the toc table of the docu page to figure stuff out. For a beginner, having this possibility to switch from birds to frog perspective inside one page is really great. They could do a better job on integrating the page-internal toc navigation though.

That would work just as well, I think.

There's a bit of serendipity in a big page like that, where you can learn more than you expected. But it comes at the cost of distracting you from whatever it was you came to find.

Reply on news.ycombinator.com