To developers of Rails: Feeble documentation - weakness of Ruby and the Ruby on Rails (2nd edition)

Directly I apologize for my English - I used the automatic translator. If there is a possibility, find the person, knowing Russian better, it will translate you correctly the text.

Address to developers of Ruby and Ruby on Rails:

(If someone has a possibility to communicate directly with developers of these systems (Ruby and Ruby on Rails), please, hand over them this information.)

Hi

It would be desirable to express the subjective judgement on a problem of popularity of Ruby and the Ruby on Rails in particular. It is very beautiful and laconic language, very powerful language. I studied it according to the book, it was necessary to read 2 times up to the end to understand all details. And I not for nothing spent the time. It is very powerful tool for development. The same it is possible to tell and about the Ruby on Rails. Agree that it not the simplest systems that here so from the first everything to understand. I am the professional programmer with more than 20-year experience, studied many systems and programming languages - Pascal, C, C ++, Java, Prolog, Delphi, PHP, developed different systems. Don't think that I am a school student any. Knowing all this languages, I after all delighted with Ruby!

And here, by the way, about PHP. I learned it an experimental way, with site use www.php.net. Here in than all charm of this site - there is ALL and directly! There is as the language syntax description, and the description of all functions in case of what if it is function, that is links to the similar functions accompanying. Everything is easy and simple - the person gradually learns more and more, plunges into this environment more and more development. Any puzzles and guesses. For me the study of PHP was simple and fast.

And so I have a question. Why, possessing so powerful possibilities, Ruby and Ruby on Rails still possess such feeble documentation? After all this most important in popularity of ANY system - existence of GOOD documentation when to the person always is where to address for the reference information instead of to build own guesses, not to rummage in source codes. To rummage in source codes is programming for the sake of programming, and after all people simply want to use the tool. To receive quickly necessary information on system is already a success half, in my judgement. Not enough description of functions, is necessary still that the person could see similar functions that could follow as on a chain. You look on documentation on the same www.php.net also look at Ruby and Ruby on Rails documentation. In yours documentation (Index of Files, Classes & Methods in Ruby 1.9.3 (Ruby 1.9.3)), for example, I couldn't find the description of method_missing, but in other source (http://apidock.com/) it is. Unless it is impossible to create a normal site with documentation where there would be all and directly? Why the person shall guess, rummage about something in source codes? About Ruby on Rails documentation (http://api.rubyonrails.org/) I generally am silent - there is no description many methods if there is a description, not clearly what it can accept parameters and that they mean, there is no description of classes, their correlations.

You developed such fine system, a magnificent programming language, excellent framework, so why you can't develop normal, distinct documentation? In it popularity of PHP and weakness of Ruby, only in it. There would be same good documentation, then long ago Ruby would walk ahead Planet (Earth) at all - ("To be number one"). It seems to me long ago already it is time to supply team of developers team of developers of DOCUMENTATION. After all the maturity of any product is characterized just by convenient and extensive documentation, including.

I think that many are stopped just by this moment in study when people face that simply can't move easily further in study and use of these systems - Ruby and the Ruby on Rails.

And once again thanks for so excellent tools!

Yours faithfully, Sergey

from forum "Ruby":

http://api.rubyonrails.org/ - disgusting documentation! There are no descriptions of all classes, there are no descriptions of their correlations, there are no descriptions of many methods (there are only references of existence of methods, names of methods, but unless it is quite enough of it?), there are no descriptions of ALL parameters of methods.

http://guides.rubyonrails.org/ - thhe easy-to-follow tutorial (for beginers) - here isn't present any detail description of API.

Compare, for example, with a site www.php.net and you will see a big difference.

I use both PHP and Ruby therefore I know about what I tell.

A more appropriate approach I believe would be to add what you believe are good comments to one of the files and submit a pull request.

-kevin

Sergey Ezhov wrote in post #1057962:

Compare, for example, with a site www.php.net and you will see a big difference.

I use both PHP and Ruby therefore I know about what I tell.

Yes Rails documentation could be better. However, it is completely unfair to compare programming language documentation to object library/framework documentation.

Programming languages, like PHP and Ruby, are easy to document. Languages are MUCH smaller in scope than frameworks. If every method, of every class, were fully documented by the team building Rails then nothing would ever get done.

Also of note is that PHP has been around a lot longer, and changes at a much slower pace than Rails.

Rails documentation is open for anyone to contribute. Complaining about it is useless and certainly won't make the documentation better. Someone caring enough to write documentation is what's going to make the documentation better.

+1

These are all excuses. All problem in an approach to documentation creation, unwillingness to create normal documentation. Creators of RoR should try to create good documentation, and not just good framework.

There is a set of examples where people approached more responsibly to documentation creation, for example: http://www.yiiframework.com, http://kohanaframework.org, http://framework.zend.com/

I suppose, they reflected on convenience of use of tools to developers.

There is a set of examples where people approached more responsibly to documentation creation, for example: http://www.yiiframework.com, http://kohanaframework.org, http://framework.zend.com/

There is an Agile methodology argument that documentation should be written by those that need it. Perhaps you could pair with a developer and help to contribute, as you have very clear ideas of what would be useful.

I suppose, they reflected on convenience of use of tools to developers.

clearest documentation for the code I write; just like I can't do UI design, colour-palette mixing, or a host of other associated skills. The skill of being able to write good documentation isn't always going to overlap with being able to write good code - so maybe the lack of good docs is more down to a lack of people who are able to write the docs contributing, rather than any malicious intent of the core developers.

As and aside; if you compare the Rails core to lots of other frameworks (particularly some of those written in PHP that you cite) the source is a *lot* more "self documenting" when it's written well in Ruby. And it's a million times better than *badly* written PHP. So given the choice, I'd rather have good code with sparse docs, than poor code with good docs.

YMMV

And how about a good documentary code and all as good documentation to it?

For some reason developers of PHP weren't too lazy to create documentation design team. I do not think that those who well write documentation as well write also a code. But they are able to write well documentation.

was:

I on the contrary want, that Ruby the first because it is fine language and the fine tool for developers. But to be the first, it is necessary to do a little more than it is simple to write the fine tool - at least to make rather good documentation.

I on the contrary want, that Ruby became the first, even more popular because it is fine language and the fine tool for developers. But to be the first, it is necessary to do a little more than it is simple to write the fine tool - at least to make rather good documentation.

I assume that because you're using Ruby Forum, you're not quoting. Please bear in mind that the forum is just a wrapper that some people use to hide the mailing list. For those of us who use the mailing list, un-quoted replies are barely legible.

And how about a good documentary code and all as good documentation to it?

Of course, that's the ideal situation :slight_smile: Which of those frameworks has that? :wink:

For some reason developers of PHP weren't too lazy to create documentation design team.

Again, you're confusing "PHP" the language, with "Rails" the framework. Ruby has *very good* (in my opinion) API documentation - much better than the comment/discussion-ridden PHP documentation.

Let me just let you know, in case you were assuming, I'm nothing to do with Rails - I'm just a developer like yourself. But I do wince when I read phrases like "too lazy", as that implies a concious decision - an allegation that's liable to rile some people. I'm happy to give you the benefit of the doubt, as you've said that English is not your first language (although, I think you're making a great effort if you're not using a translator *applauds*). But you haven't answered my suggestion that if you think the core team are lacking in documentation skills, could you help contribute?

I don't know, what advantage is received by developers from popularity of language, from popularity of framework. But the fact remains. One develop a product from beginning to end, others - hope that people will get into source codes and all will understand, or someone another will write good documentation. If it is open-source the project, it is not necessary to hope that someone another will complete for you documentation.

Really very many people stop and leave from Ruby and Ruby on Rails use only in the absence of good documentation. Documentation is a lifebuoy for the beginner. And you suggest to rush to study of source codes directly. It very much frightens off beginners.

Michael Pavling wrote in post #1058271:

And how about a good documentary code and all as good documentation to it?

Of course, that's the ideal situation :slight_smile: Which of those frameworks has that? :wink:

Nobody. But they attract in operation of developers of documentation - they want to make the product of development really popular. I also speak about it.

For some reason developers of PHP weren't too lazy to create documentation design team.

Again, you're confusing "PHP" the language, with "Rails" the framework. Ruby has *very good* (in my opinion) API documentation - much better than the comment/discussion-ridden PHP documentation.

Ruby is popular thanks to the Ruby on Rails, in particular. And the Ruby on Rails is very badly documented. As a result, it repels beginners from Ruby.

But you haven't answered my suggestion that if you think the core team are lacking in documentation skills, could you help contribute?

I started to use only recently the Ruby on Rails. Yet the professional also I do not know all subtleties and details of this framework. The vicious circle turns out. To develop good documentation - it is necessary to know well RoR. In order that it is good to know RoR - good documentation is necessary. Better than all Rubies on Rails developers certainly know.

I don't know, what advantage is received by developers from popularity of language, from popularity of framework.

Again, you're posting without quoting, so I have no idea what you're referring to.

Really very many people stop and leave from Ruby and Ruby on Rails use only in the absence of good documentation.

What documentation *is* missing? There are dozens of "getting started with Rails" books, and indeed, if you type that phrase into your search engine of choice, you get a massive amount of results, including:

  Getting Started with Rails — Ruby on Rails Guides   #310 Getting Started with Rails - RailsCasts   Getting Started with Rails 3.x on Heroku | Heroku Dev Center

And let's not forget what I already referred to as the great Ruby API docs:   Index of Classes & Methods in Ruby 1.8.6 (Ruby 1.8.6)   Index of Classes & Methods in Ruby 1.8.7 (Ruby 1.8.7)   Index of Files, Classes & Methods in Ruby 1.9.3 (Ruby 1.9.3)

And the very handy Rails API docs:   http://api.rubyonrails.org/

So what *is* extra that is needed in your view? If you've got a great idea, then awesome! Please contribute it, I'd love to see it.

And you suggest to rush to study of source codes directly. It very much frightens off beginners.

No, I *didn't* suggest it (and if you'd quoted what I said, you would see it). I said that *I* find well-written-source-code-with-poor-docs better than poorly-written-code-with-good-docs, but I *never* said I agreed with you that the Ruby/Rails docs are poor. Personally, I think they're perfectly good, and the associated contributions from the community are of varying quality, but generally good/excellent. But I'm happy to discuss with you your disagreement.

There's always room for more tutorials... please contribute! :slight_smile:

And let's not forget what I already referred to as the great Ruby API docs:   Index of Classes & Methods in Ruby 1.8.6 (Ruby 1.8.6)   Index of Classes & Methods in Ruby 1.8.7 (Ruby 1.8.7)   Index of Files, Classes & Methods in Ruby 1.9.3 (Ruby 1.9.3)

In Index of Files, Classes & Methods in Ruby 1.9.3 (Ruby 1.9.3) -> Core

Try, for example, to find a method "method_missing". Fail! How I can trust documentation in which methods about which I already know aren't described?

And the very handy Rails API docs:   http://api.rubyonrails.org/

Bad documentation! There are no descriptions of many classes, there are no descriptions of many methods, there are no descriptions of parameters of methods, there are no descriptions of ALL possible parameter values of methods.

Try, for example, to find a method "method_missing". Fail!

http://rubydoc.info/stdlib/core/1.9.3/BasicObject#method_missing-instance_method

example fail...

How I can trust documentation in which methods about which I already know aren't described?

A null hypothesis.

And the very handy Rails API docs: http://api.rubyonrails.org/

Bad documentation! There are no descriptions of many classes, there are no descriptions of many methods, there are no descriptions of parameters of methods, there are no descriptions of ALL possible parameter values of methods.

*sigh* so write them... or ask about specific places where you're stuck.

Look, you're talking about things being difficult for beginners, and then wave "method_missing" as an example - to play with that is pretty serious meta-programming which will blow up horribly if you don't know what you're doing. There *is* plenty of reference for *how* to use method_missing if you look for it, even if it is not mentioned in the core docs.

If you expect *everything* to be totally complete before you start using it, then you're going to be disappointed (in life, not just in Ruby/Rails). In all seriousness, if a few holes in documentation frustrate someone so much that they "stop and leave from Ruby and Rails" then maybe it wasn't for them in the first place - it takes all sorts to run the world, and everything is not for everyone :-/

Michael Pavling wrote in post #1058287:

Look, you're talking about things being difficult for beginners, and then wave "method_missing" as an example - to play with that is pretty serious meta-programming which will blow up horribly if you don't know what you're doing. There *is* plenty of reference for *how* to use method_missing if you look for it, even if it is not mentioned in the core docs.

It was simply the example. The description of a method isn't found, anyway.

Sergey

The amount of words you have written complaining about the state of the documentation you could have written several entries.

Put up or shut up.