News for hackers. Stuff that matters.
Re:Rails 3 Has Great Documentation by michaelfairley on Saturday August 28, 2010 @07:23PM (#1642625)
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

Re:Rails 3 Has Great Documentation by wwortiz on Saturday August 28, 2010 @07:30PM (#1642641)
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.

Re:Rails 3 Has Great Documentation by jamesbritt on Saturday August 28, 2010 @08:14PM (#1642722)
"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]

Re:Rails 3 Has Great Documentation by michaelfairley on Saturday August 28, 2010 @07:57PM (#1642699)
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...

Re:Rails 3 Has Great Documentation by jimbokun on Saturday August 28, 2010 @09:02PM (#1642803)
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.

Re:Rails 3 Has Great Documentation by michaelfairley on Saturday August 28, 2010 @09:05PM (#1642813)
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?
Re:Rails 3 Has Great Documentation by hermanthegerman on Sunday August 29, 2010 @04:38AM (#1643457)
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.

Re:Rails 3 Has Great Documentation by jimbokun on Saturday August 28, 2010 @09:26PM (#1642850)
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.