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

Ruby
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

I think you are a bit confused.

Ruby is a programming language. Rails is a web framework (which just
happens to be written in Ruby). They are two completely separate things.
Complaining about them both together is like complaining about Sendmail
and C together (just because Sendmail happens to be written in C)

If you have suggestions for Rails, please send them to a Rails forum or
mailing list.

As for documentation: there is very good commercial documentation
available for both Ruby and Rails - for a few dollars you can get very
good PDFs. If you don’t want to pay this, then the first edition of the
Pickaxe book is still available online for free and remains a good
starting point: Programming Ruby: The Pragmatic Programmer's Guide

I agree with you that the bundled documentation for the ruby language
itself is poor, but I don’t think that complaining about it will help.
If you’d like to contribute, I’m sure your efforts would be gratefully
accepted.

3

Brian C. wrote in post #1057913:

I think you are a bit confused.

Ruby is a programming language. Rails is a web framework (which just
happens to be written in Ruby). They are two completely separate things.
Complaining about them both together is like complaining about Sendmail
and C together (just because Sendmail happens to be written in C)

That’s just the point that it concerns both environments of development

  • Ruby and Ruby on Rails.

If you have suggestions for Rails, please send them to a Rails forum or
mailing list.

I wrote and to the Ruby on Rails forum too.

4

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.

5

On Mon, Apr 23, 2012 at 5:11 AM, Brian C. [email protected]
wrote:

As for documentation: there is very good commercial documentation

Posted via http://www.ruby-forum.com/.

Hmm, don’t have the email you’re responding to in my inbox -.^

Anyway, I think the OP is wrong, Rails has really great docs:

http://api.rubyonrails.org/

6

Hello,

Since you’re into ‘serious’ development why not try to buy a book? The
pickAxe is a good start and there are others…

On 23 Απρ 2012, at 15:20 , Sergey E. wrote:

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

–
Posted via http://www.ruby-forum.com/.

regards

Panagiotis A.

7

On Mon, Apr 23, 2012 at 9:17 PM, Ryan D.
[email protected]wrote:

That’s the oldest and most established subproject in rails… meaning, it
has the least excuse to be less than 50% documented.

For some reason Gmail doesn’t show me the origin of this thread. But
that
remark seems unfair to me.

For starters, that statistic presented like that, cold, is not very
meaningful. You’d need to add how many of the undocumented methods are
public interface. Because we are talking about end users, to which
internal
documentation is not a concern.

The documentation of Ruby on Rails has sure room for improvement, but
you
can’t deny that since docrails was created the documentation is good. We
get many documentation contribs via docrails, the guides, patches are
not
accepted without docs coverage. Could it be better? Always, but this
project has documentation as a first class citizen nowadays.

I wanted to state my point of view. I have interest zero on discussing
whether a certain adjective is appropriate or not.

Ruby has the same problem

No, Ruby has a way worse problem.

I am not complaining (in open source I very rarely complain), but to
express my opinion about this, it is a matter of fact that Ruby
documentation can’t be compared with the quantity and quality of Rails
documentation.

8

On Apr 23, 2012, at 06:07 , Josh C. wrote:

Anyway, I think the OP is wrong, Rails has really great docs:

http://guides.rubyonrails.org/
http://api.rubyonrails.org/

I can’t believe the attitude I’m seeing in this thread. Someone writes a
very thorough and self-admittedly subjective critique of our beloved
ruby (and rails) and all he gets is people jumping down his throat
saying he’s wrong or confused. He’s not. He’s totally right.

Really great? I couldn’t disagree more. I completely agree with the OP
that both ruby and rails have a long way to go before our documentation
is “really great”. For example, rdoc -C lib inside of activerecord:

Files: 144

Classes: 82 ( 28 undocumented)
Modules: 90 ( 63 undocumented)
Constants: 21 ( 20 undocumented)
Attributes: 91 ( 84 undocumented)
Methods: 822 (385 undocumented)

Total: 1106 (580 undocumented)
47.56% documented

That’s the oldest and most established subproject in rails… meaning,
it has the least excuse to be less than 50% documented.

Ruby has the same problem, but at least Eric H. and others are
(semi-)actively doing something about it. It still has a long way to go
before it is “really great”:

Files: 764

Classes: 1293 ( 620 undocumented)
Modules: 302 ( 146 undocumented)
Constants: 2195 ( 828 undocumented)
Attributes: 1013 ( 438 undocumented)
Methods: 9440 (2459 undocumented) ONE IN FOUR!

Total: 14243 (4491 undocumented)
68.47% documented

The numbers speak for themselves, as do the really basic questions on
this mailing-list, ruby-forum, stackexchange, etc.

And before anyone starts up on the “great” commercial documentation
available… do we really want to have a paywall as our barrier to
entry?

9

On Mon, Apr 23, 2012 at 8:20 AM, Sergey E. [email protected]
wrote:

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 no
descriptions of parameters of these methods.

You might try http://apidock.com. It’s the same information, but I
prefer
the interface.

That said, there are 1100 classes in Rails. A list of each of them and
what
they do isn’t going to be particularly helpful, since there are very few
you actually need to use as an end user of the framework.

Correlations between classes are definitely documented, although as
always
the documentation could be better. See the documentation for
ActiveRecord,
for example:

http://apidock.com/rails/ActiveRecord/Base

10

On Apr 23, 2012, at 13:05 , Xavier N. wrote:

Total: 1106 (580 undocumented)
47.56% documented

That’s the oldest and most established subproject in rails… meaning, it has
the least excuse to be less than 50% documented.

For some reason Gmail doesn’t show me the origin of this thread. But that remark
seems unfair to me.

For starters, that statistic presented like that, cold, is not very meaningful.
You’d need to add how many of the undocumented methods are public interface.
Because we are talking about end users, to which internal documentation is not a
concern.

Wrong. Rdoc -C doesn’t count anything marked with :nodoc: nor does it
count methods that are private. So there is no reason why this number
shouldn’t be 100%.

11

On Mon, Apr 23, 2012 at 3:30 PM, Ryan D.
[email protected]wrote:

Wrong. Rdoc -C doesn’t count anything marked with :nodoc: nor does it
count methods that are private. So there is no reason why this number
shouldn’t be 100%.

How many of the un(der)documented classes/methods are actually useful to
end-users of the framework though? I’m not excusing the current state of
the documentation, but I’d hope the majority of what end users would
actually use is documented.

12

On Mon, Apr 23, 2012 at 2:17 PM, Ryan D.
[email protected]wrote:

(and rails) and all he gets is people jumping down his throat saying he’s
wrong or confused. He’s not. He’s totally right.

As I said “Hmm, don’t have the email you’re responding to in my inbox
-.^”
so I can’t see the “thorough and self-admittedly subjective critique”.
This
issue has been brought up countless times but looks like it won’t ever
be
addressed.

Really great? I couldn’t disagree more. I completely agree with the OP
that

both ruby and rails have a long way to go before our documentation is
“really great”. For example, rdoc -C lib inside of activerecord:

Okay, but how frequently do you need to know how something works and
find
its not documented? For me that’s pretty rare. And often the docs would
be
redundant as the name is sufficiently descriptive. Worst case, you
expand
the code view.

Also, I do think the guides are “really great”, they’re full of
examples,
diagrams, notes, they’re well structured, and contain both a breadth and
depth of information. They omit some of the less relevant parts of
Rails,
and for those cases, the API usually works for me. It’s pretty rare for
me
to have to go digging through code.

Might also be worth noting that I live on Pry, and do a large amount of
self-discovery with that.

13

On Tue, Apr 24, 2012 at 4:20 AM, Tony A. [email protected]
wrote:

You might try http://apidock.com. It’s the same information, but I prefer
the interface.

+1 on apidock. has notes and references to related
classes/functions(and search is fast too)… but unfortunately
apidock does not show a list/links of all the undocumented
methods/classes (so we can add what is immediately missing… like the
case of missing method_missing. lol :slight_smile: …

thanks for apidock
kind regards -botp