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
(http://www.ruby-doc.org/core-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:

  http://guides.rubyonrails.org/getting_started.html
  http://railscasts.com/episodes/310-getting-started-with-rails
  https://devcenter.heroku.com/articles/rails3

And let's not forget what I already referred to as the great Ruby API docs:
  http://www.ruby-doc.org/core-1.8.6/
  http://www.ruby-doc.org/core-1.8.7/
  http://www.ruby-doc.org/core-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:
  http://www.ruby-doc.org/core-1.8.6/
  http://www.ruby-doc.org/core-1.8.7/
  http://www.ruby-doc.org/core-1.9.3/

In http://www.ruby-doc.org/core-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.