5 ms·

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 asi

by wwortiz 16y ago

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.

petercooper 16y ago
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.)
- wwortiz 16y ago
  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.
steveklabnik 16y ago
> 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.
- wwortiz 16y ago
  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.
michaelfairley 16y ago
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 http://docs.python.org/library/stdtypes.html
- wwortiz 16y ago
  Compare that with this: http://ruby-doc.org/ruby-1.9/index.html 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.
  - michaelfairley 16y ago
    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 http://ruby-doc.org/core/classes/String.html [2] http://cupi2.uniandes.edu.co/site/images/recursos/javadoc/j2se/1.5.0/docs/api/java/lang/String.html http://cupi2.uniandes.edu.co/site/images/recursos/javadoc/j2...
  - jamesbritt 16y ago
    "Compare that with this: http://ruby-doc.org/ruby-1.9/index.html 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]

by wwortiz 16y ago

petercooper 16y ago

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

wwortiz 16y ago
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.

steveklabnik 16y ago

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

wwortiz 16y ago
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.

michaelfairley 16y ago

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 http://docs.python.org/library/stdtypes.html

wwortiz 16y ago
Compare that with this: http://ruby-doc.org/ruby-1.9/index.html 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.
- michaelfairley 16y ago
  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 http://ruby-doc.org/core/classes/String.html [2] http://cupi2.uniandes.edu.co/site/images/recursos/javadoc/j2se/1.5.0/docs/api/java/lang/String.html http://cupi2.uniandes.edu.co/site/images/recursos/javadoc/j2...
- jamesbritt 16y ago
  "Compare that with this: http://ruby-doc.org/ruby-1.9/index.html 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]