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

Rails
1

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

===

Обращение к разработчикам Ruby и Ruby on Rails:

Здравствуйте

Хочется высказать свое субъективное мнение на проблему популярности Ruby
и Ruby on Rails в частности. Это очень красивый и лаконичный язык, очень
мощный язык. Я его изучил по книге, пришлось прочитать 2 раза, чтобы до
конца уяснить все детали. И я не зря потратил свое время. Это очень
мощный инструмент для разработки. То же самое можно сказать и про Ruby
on Rails. Согласитесь, что это не самые простые системы, чтобы вот так с
первого раза все понять. Я профессиональный программист с более чем
20-летним опытом работы, изучил немало систем и языков программирования

  • Pascal, C, C++, Java, Prolog, Delphi, PHP, разрабатывал различные
    системы. Не думайте, что я школьник какой-нибудь. Зная все эти языки, я
    все-таки в восторге от Ruby!

И вот, кстати, о PHP. Его я выучил экспериментальным путем, с
использованием сайта www.php.net. Вот в чем вся прелесть этого сайта -
там есть ВСЕ и сразу! Там есть как описание синтаксиса языка, так и
описание всех функций, при чем если это функция, то есть ссылки на
похожие функции, сопутствующие. Все легко и просто - человек постепенно
все больше и больше узнает, все больше погружается в эту среду
разработки. Никаких головоломок и догадок. Для меня изучение PHP было
простым и быстрым.

Так вот у меня вопрос. Почему, обладая столь мощными возможностями, Ruby
и Ruby on Rails до сих пор обладают такой слабой документацией? Ведь это
самое главное в популярности ЛЮБОЙ системы - наличие ХОРОШЕЙ
документации, когда человеку всегда есть куда обратиться за справочной
информацией, а не строить собственные догадки, не рыться в исходниках.
Рыться в исходниках - это программирование ради программирования, а ведь
люди просто хотят использовать инструмент. Получить быстро нужную
информацию о системе - это уже половина успеха, я считаю. Мало описания
функций, надо еще чтобы человек мог видеть похожие функции, чтобы мог
следовать как по цепочке.
Вы посмотрите на документацию на том же www.php.net и посмотрите на
документацию Ruby и Ruby on Rails. В вашей документации
(Index of Files, Classes & Methods in Ruby 1.9.3 (Ruby 1.9.3)), например, я не смог найти
описание method_missing, зато в другом источнике (http://apidock.com/)
оно есть.
Разве нельзя создать нормальный сайт с документацией, где было бы все и
сразу? Почему человек должен о чем-то догадываться, рыться в исходниках?
Про документацию Ruby on Rails (http://api.rubyonrails.org/) я вообще
молчу - нет описания многих методов, если есть описание, то не понятно
какие он может принимать параметры и что они означают, нет описания
классов, их взаимосвязей.

Вы разработали такую прекрасную систему, великолепный язык
программирования, превосходный фреймворк, так почему вы не можете
разработать нормальную, внятную документацию? В этом популярность PHP и
слабость Ruby, только в этом. Была бы такая же хорошая документация,
тогда давно бы Ruby шагал впереди планеты всей. Мне кажется давно уже
пора снабдить команду разработчиков командой разработчиков ДОКУМЕНТАЦИИ.
Ведь зрелость любого продукта характеризуется как раз удобной и обширной
документацией, в том числе.

Я думаю, что многих останавливает как раз этот момент в изучении, когда
люди сталкиваются с тем, что просто не могут легко двигаться дальше в
изучении и использовании этих систем - Ruby и Ruby on Rails.

И еще раз спасибо за столь превосходные инструменты!

С Уважением, Сергей

2

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.

3

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

4

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

5

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.

Framework isn’t much more difficult for documenting. If framework
changes, it is better all these changes would be reflected in
documentation, instead of to rummage on source codes.
It is enough to describe ALL methods of the main classes both ALL
possible parameters and values of these parameters.

And the main thing - it is not necessary to shift everything on
automatic generation of documentation from source codes, it is necessary
to approach to process more creatively.

6

+1

7

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.

8

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.

For this reason PHP and php-frameworks remain more popular and will be
more popular and further while the Ruby on Rails will possess so
inconvenient documentation.

I on the contrary want, that Ruby was 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.

Language “C” became popular thanks to system Unix, Ruby becomes popular
thanking the Ruby on Rails. So why not to try - to make everything
really well.

9

On 25 April 2012 06:03, Sergey E. [email protected] wrote:

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.

From my own experience, I find that I can’t necessarily write the
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

10

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.

11

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.

12

Michael P. wrote in post #1058271:

On 25 April 2012 09:50, Sergey E. [email protected] wrote:

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.

13

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 other Ruby on Rails developers
certainly know.

14

On 25 April 2012 10:20, Sergey E. [email protected] wrote:

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:

15

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.

16

On 25 April 2012 11:11, Sergey E. [email protected] wrote:

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 :-/

17

Michael P. wrote in post #1058287:

On 25 April 2012 11:11, Sergey E. [email protected] wrote:

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

Class: BasicObject — Documentation for core (1.9.3)

example fail…

And generally it absolutely other site. Whether not so?
Your example fail!

This way please: Index of Files, Classes & Methods in Ruby 1.9.3 (Ruby 1.9.3) → Core

18

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.
I didn’t begin to check the description of other methods, but the trust
to documentation is already lost. How many still such not described
methods can be? Who knows?

19

On 25 April 2012 09:50, Sergey E. [email protected] wrote:

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?

20

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.