Hacker News Reader

Comment by wwortiz | Hacker News Reader

Isn't that only from a large community, when I think of documentation I think of a central place to find it and this is why I use python and not ruby. As an aside the ruby docs are annoying for me to use however I quite enjoy the way pythons docs are built.

Similarly when you look at this post you see that rails has "great" documentation through the means of a large amount of differing non-central sites that require some effort to go about finding as well as navigating. Though it is much better than when rails was still young.

View on HN

Yeah. In my experience, Rubyists are more likely to be solo developers, self starters and/or be keen to improve things/reinvent wheels rather than necessarily work on "official" projects with all the bureaucracy that's involved. I wouldn't dare to speak for all Rubyists but, in general, I'd say the typical Rubyist is very anti-bureaucracy (more so than developers of any other group I've experienced).

There have been tons of Ruby documentation sites over the years and if all that effort had been put into developing a good system for the "official" documentation, it'd probably the best of any language ;-) But Ruby is very "long tail" when it comes to deciding what sites to read, mailing lists to use, etc. There are few de facto points of congregation.

That said, I'm not criticizing, because I'm the same (I want to run my own gigs, not fit in with someone else's system) and that's what I like about Ruby and Rubyists. You don't get a single "official" book of documentation about math, architecture, or English language syntax. Instead, everyone releases their own attempts and a wide variety of viewpoints and coverage is available.

In this way, Ruby feels more like a discipline or "way" of doing things than a single, specified entity that can be centrally documented well.

(I'm talking from a Ruby POV rather than a Rails one, since you brought up Ruby specifically in comparison to Python. Rails has a much more bureaucratic and centralized community than Ruby does. Rails' official documentation is also miles ahead of Ruby's.)

There really is a ruby way of doing things and from the outside it is interesting but not something I feel like I would benefit from. Ruby moves fast and the community moves fast with it and this doesn't fit me well or the way I work.

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

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.

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...

"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]

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?

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.

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.

> when I think of documentation I think of a central place to find it

While your other points still stand, there is quite a bit of central documentation, and it's mentioned in the article. The fact that there's also a ton of extra documentation that other people have done in other places is just icing on the cake.

Even the central documentation is split between two subdomains with edge cases for each. You have the api reference and then you have the guides (which is much better docs but still lacking in navigation and extensiveness.) It isn't necessarily a bad thing the way rails docs are, personally I just think the ruby community moves way too fast and in that the extensive docs tend to suffer.

Reply on news.ycombinator.com