To developers of Rails: Feeble documentation - weakness of Ruby and the Ruby on Rails (2nd edition)
Sergey Ezhov
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
===
Обращение к разработчикам 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. В вашей документации
(http://www.ruby-doc.org/core-1.9.3/), например, я не смог найти
описание method_missing, зато в другом источнике (http://apidock.com/)
оно есть.
Разве нельзя создать нормальный сайт с документацией, где было бы все и
сразу? Почему человек должен о чем-то догадываться, рыться в исходниках?
Про документацию Ruby on Rails (http://api.rubyonrails.org/) я вообще
молчу - нет описания многих методов, если есть описание, то не понятно
какие он может принимать параметры и что они означают, нет описания
классов, их взаимосвязей.
Вы разработали такую прекрасную систему, великолепный язык
программирования, превосходный фреймворк, так почему вы не можете
разработать нормальную, внятную документацию? В этом популярность PHP и
слабость Ruby, только в этом. Была бы такая же хорошая документация,
тогда давно бы Ruby шагал впереди планеты всей. Мне кажется давно уже
пора снабдить команду разработчиков командой разработчиков ДОКУМЕНТАЦИИ.
Ведь зрелость любого продукта характеризуется как раз удобной и обширной
документацией, в том числе.
Я думаю, что многих останавливает как раз этот момент в изучении, когда
люди сталкиваются с тем, что просто не могут легко двигаться дальше в
изучении и использовании этих систем - Ruby и Ruby on Rails.
И еще раз спасибо за столь превосходные инструменты!
С Уважением, Сергей
---
--
Posted via http://www.ruby-forum.com/.
Sergey Ezhov
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.
Kevin Bedell
are good comments to one of the files and submit a pull request.
-kevin
> --
> You received this message because you are subscribed to the Google Groups "Ruby on Rails: Talk" group.
> To post to this group, send email to rubyonra...@googlegroups.com.
> To unsubscribe from this group, send email to rubyonrails-ta...@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/rubyonrails-talk?hl=en.
>
Robert Walker
> 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.
Abram
Sergey Ezhov
creation, unwillingness to create normal documentation. Creators of RoR
should try to create good documentation, and not just good framework.
Sergey Ezhov
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.
Michael Pavling
> 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
Sergey Ezhov
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.
Sergey Ezhov
>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.
Michael Pavling
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 :-)
Which of those frameworks has that? ;-)
> 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?
Sergey Ezhov
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.
Sergey Ezhov
>> And how about a good documentary code and all as good documentation to
>> it?
>
> Of course, that's the ideal situation :-)
> Which of those frameworks has that? ;-)
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.
on Rails is very badly documented. As a result, it repels beginners from
Ruby.
Sergey Ezhov
>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.
Michael Pavling
> 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! :-)
Sergey Ezhov
> 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.
Michael Pavling
> 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 :-/
Sergey Ezhov
> On 25 April 2012 11:11, Sergey Ezhov <li...@ruby-forum.com> 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...
And generally it absolutely other site. Whether not so?
Your example fail!
This way please: http://www.ruby-doc.org/core-1.9.3/ -> Core
Sergey Ezhov
> 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.
anyway.
Peter Hickman
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.
Matt Jones
On Wednesday, 25 April 2012 01:03:15 UTC-4, Ruby-Forum.com User wrote:
There is a set of examples where people approached more responsibly to
documentation creation, for example: http://www.yiiframework.com,
http://kohanaframework.org,
Kevin Bedell
documentation while refusing to contribute to it makes you come across
like an entitled little snit.
Zachary Scott
Give it a look and see where you can help out. You'll find that the
rails guides community is very much active[2] and fluent.
1: http://weblog.rubyonrails.org/2012/3/7/what-is-docrails/
2: http://github.com/lifo/docrails
Sergey Ezhov
with the Ruby on Rails, I will try to make the contribution to
documenting.
For now I only stated the opinion of an existing problem in study for
beginners.
Very much I hope that developers of the Ruby on Rails will take into
consideration my notes.
Greg Donald
> Languages are MUCH smaller in scope than frameworks.
built on. And pretty much any language or compiler you create with
LLVM/clang project will be smaller than LLVM itself.
--
Greg Donald
Kevin Bedell
Ruby recently eclipsed 1 million lines of code.
Michael Pavling
> On Tue, Apr 24, 2012 at 4:10 PM, Robert Walker <li...@ruby-forum.com> wrote:
>> Languages are MUCH smaller in scope than frameworks.
> Ruby recently eclipsed 1 million lines of code.
"scope" != "LoC"
Jedrin
I do sometimes wonder about one thing, which is that Rails keep
changing and does not have backward compatability in many cases. When
you google for something to try to figure out how to do it in Rails,
you may get some hits from how you might have done it the old way
which has now changed. I am not sure if that could be a problem with
how google works in conjunction with this Rails approach. The same
thing may happen with older books on rails, but I still like Ruby more
than Perl, PHP, and Java in many ways
Jedrin
I don't believe there is any perfect language, thus any language will
have some weakness. Ruby is still my favorite language however.
I do sometimes feel in some ways Java may have some strengths where
Ruby lacks, but I like writing code in Ruby quite a bit.
Kevin McCaughey
> every class, were fully documented by the team building Rails then
> nothing would ever get done.
I have been learning for a while now, and my journey started with Ruby.
I am reading that RoR is falling out of fashion. I think the reason for
that is all the problems + lack of proper documentation. Possibly also
the meandering development, which seems to follow no logic.
STOP! Stop adding bits on and go back and tidy up the mess.
R/RoR is a disaster as compared to other programming languages, and
unless it gets things (a) working and (b) documented, it will fall to
the next big thing (node?).
All those screencasts I watched with machines that were already set up
with 123 steps done, so they didn't splutter errors every step of the
way, which is the ACTUAL experience that anyone new to R/RoR will have.
I say this at the end of a day spent yet again fighting RoR. The asnwers
I needed I found in some obscure forum, "oh error 6571, yeah that one!
Yeah well you do these 10 steps, then do that, do this, bind this with
that, run bundler, edit the config.yml with the string you get at such
and such's blog..." etc etc.
It's a total mess. If the community wants to be taken in any way
seriously they should stop all development, fix it, document it and get
it installing and (within reason) able to be used in production. For me
it has been nothing but one bloody problem over another since I started
on this 3 months ago. C++ was much, much easier (15 years ago). Your
community is a fragmented mess too frankly.
Sorry, just had to get it out - Sergie just confirmed what I have been
trying to lie to myself about.
Robert Walker
>> If every method, of
>> every class, were fully documented by the team building Rails then
>> nothing would ever get done.
>
> This is the perenail excuse - It's too big, so we just won't bother.
cool stuff done in Rails. This leads me to the think that maybe the
problem lies somewhere besides the "poor" docs? Just a thought.
Sergey Ezhov
farther to try to work with Rails because of such "documentation". Not
only beginners in programming, but also professionals pass by and leave.
I want, that Rails became even more successful product. I like Ruby, I
like ideas of Rails. But a lot of things spoils ""poor" docs".
Sergey Ezhov
Karthikeyan A.K
On Monday, April 23, 2012 11:27:40 AM UTC+5:30, Ruby-Forum.com User wrote:
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
===
Обращение к разработчикам 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. В вашей документации
(http://www.ruby-doc.org/core-1.9.3/), например, я не смог найти
описание method_missing, зато в другом источнике (http://apidock.com/)
оно есть.
Разве нельзя создать нормальный сайт с документацией, где было бы все и
сразу? Почему человек должен о чем-то догадываться, рыться в исходниках?
Про документацию Ruby on Rails (http://api.rubyonrails.org/) я вообще
молчу - нет описания многих методов, если есть описание, то не понятно
какие он может принимать параметры и что они означают, нет описания
классов, их взаимосвязей.Вы разработали такую прекрасную систему, великолепный язык
программирования, превосходный фреймворк, так почему вы не можете
разработать нормальную, внятную документацию? В этом популярность PHP и
слабость Ruby, только в этом. Была бы такая же хорошая документация,
тогда давно бы Ruby шагал впереди планеты всей. Мне кажется давно уже
пора снабдить команду разработчиков командой разработчиков ДОКУМЕНТАЦИИ.
Ведь зрелость любого продукта характеризуется как раз удобной и обширной
документацией, в том числе.Я думаю, что многих останавливает как раз этот момент в изучении, когда
люди сталкиваются с тем, что просто не могут легко двигаться дальше в
изучении и использовании этих систем - Ruby и Ruby on Rails.И еще раз спасибо за столь превосходные инструменты!
С Уважением, Сергей
---
Michael Pavling
> people have. that will surely increase number people who want to learn and
> use Rails.
times have you honestly been confounded by not finding something in
the docs? (and when you did, did you contribute to fill the hole?)
Brynjolfur Thorvardsson
I've been involved in programming and computers for way too long, but in an intermittent manner, with gaps of years doing something totally different followed by bouts of programming, each time in a different environment and with different languages. Having seen technologies come and go, I do not feel optimistic regarding the survivability of RoR.
During the '80s I was involved (in a very tiny way) with research into the theoretical underpinning of Ronald Reagans "Star Wars", the question being whether a given piece of code could be mathematically proven to be fail-save. The conclusion seemed to be a resounding "no". This was frustrating, perhaps one tended to view programming languages as being "mathematical languages" and felt that if properly written, code should follow some sort of mathematical laws.
The impression I get with RoR is that it is much closer to being an "organic language", where you can learn to speak it and become proficient but not without a significant effort. Being young is obviously a huge asset when learning languages and I suspect this to be the case here as well (as opposed to learning standard programming languages - I find Ruby easy to learn, much easier than I found learning Pascal was 30 years ago). RoR, as opposed to Ruby, is perhaps best seen as a step towards the development of truly intelligent programming languages, where the machine moves towards an understanding of human thought - not the other way round.
RoR is obviously a very temporary phenomenon and it will eventually be replaced by something totally different. It seems to have a very narrow application window which, combined with the effort of learning to "speak" RoR, sets it on the path to its own eventual demise. I'd estimate something in the region of 5 years, definitely not as much as 10.
So the question is really: Is documentation worth the effort? And the answer is probably: No. Attempting to do what Kevin suggests would probably kill RoR off much faster than it's "natural" lifespan would otherwise be.
Personally I am not willing to invest the time and effort needed to become proficient in something that, to me, seems a very temporary and fast-changing phenomenon. But I can see younger programmers benefiting hugely from their efforts in RoR, not least from being involved in development. RoR points to a future where programming will be quicker and easier, but also with a higher tolerance of individual instances of code failures. A more organic way of programming, one that moves closer to what our brains are built for - communicating, conceptualising - and away from what computers are good at - calculating and shuffling of minutiae.
Hoping to have complete documentation of future programming environments will be as futile as an American hoping to learn Japanese by reading a book on Japanese grammar.
Just my (not so humble) opinion.
Binni
-----Oprindelig meddelelse-----
Fra: rubyonra...@googlegroups.com [mailto:rubyonra...@googlegroups.com] På vegne af Kevin McCaughey
Sendt: 26. april 2012 00:04
Til: rubyonra...@googlegroups.com
Emne: [Rails] Re: To developers of Rails: Feeble documentation - weakness of Ruby and the Ruby on Rails (2nd editi
Scott Ribe
> Again.... *which* bit of documentation needs to be better... how many
> times have you honestly been confounded by not finding something in
> the docs? (and when you did, did you contribute to fill the hole?)
And I like RoR. And I'll say what you're all thinking: it's clear that the guy ranting about how you can't get anything done just didn't grok something and must not have bothered with any of the fine introductory books, because his claims are just not true. And no, RoR will not be gone in 5 years. At the time it came out it was a far better way to develop way apps, and it certainly has kept up.
But the reference docs are woefully inadequate, and this is a huge barrier to people trying to move from beginner to mastery.
--
Scott Ribe
scott...@elevated-dev.com
http://www.elevated-dev.com/
(303) 722-0567 voice
Michael Pavling
> On Apr 26, 2012, at 1:36 AM, Michael Pavling wrote:
>
>> Again.... *which* bit of documentation needs to be better
>
learned loads from the docs and source. But I do agree that not
everyone works the same way, or learns the same way, and it may be
that the docs as they are are not right for a large section of the
readership. But this comes back to the thought that if there needs to
be a different style to some of the documentation, then those that
need it need to start writing it rather than just complaining about
it.
Scott Ribe
> But this comes back to the thought that if there needs to
> be a different style to some of the documentation, then those that
> need it need to start writing it rather than just complaining about
> it.
Scott Ribe
> be a different style to some of the documentation, then those that
> need it need to start writing it rather than just complaining about
> it.
Craig White
On Apr 26, 2012, at 7:04 AM, Scott Ribe wrote:
> On Apr 26, 2012, at 7:43 AM, Michael Pavling wrote:
>
>> But this comes back to the thought that if there needs to
>> be a different style to some of the documentation, then those that
>> need it need to start writing it rather than just complaining about
>> it.
>
> Also, telling people who are trying to learn Rails and being blocked by incomplete docs to write the docs themselves is really kind of silly ;-)
but it is the reality of the open source world and your characterization of silly is simply your characterization. You should bear in mind that RoR was borne from DHH (and team) were scratching a particular itch and it was modestly effective whereupon it grew, reshaped, grew, reshaped, grew, reshaped, etc. The changes in the past 6 years have been spectacular but that meant that the documentation target has been moving rapidly too. By the time most books reach the print stage, they are out of date.
I the rails api is sufficient for documenting rails classes & methods but that the larger criticisms stem from several different areas:
- people looking for answers to things about ruby within the rails documentation, probably owing to the fact that newer rails users don't seem to be able to differentiate between them. I think that there were several books on firming up your ruby knowledge in order to make it easier to utilize the RoR framework.
- people using google to search for answers and finding wide ranging answers... many for earlier and relatively ancient rails versions and inapplicable. Likewise, stumbling on older books and tutorials that don't track to what you get when you take a modern system and 'gem install rails'
- there are quite a few thresholds that one must cross in order to become proficient with rails. Learning:
- ruby language
- mvc concepts
- routes
- gem infrastructure (bundler is making this a much easier task nowadays)
- web server deployment
- integrated testing
Thus for all of the benefits to be had from developing RoR applications, there's the expectation that getting there would be relatively simple, quick and pain free and that is not realistic. Mostly its those who have the expectation that it would be quick and simple to learn that are the ones who will decry the state of the documentation. Once you begin to figure it all out, the documentation ceases to be a barrier to entry... until then, you should probably consider the possibility that your web application abilities might not be as good as you think they are.
Craig
Peter Hickman
> Also, telling people who are trying to learn Rails and being blocked by incomplete docs to write the docs themselves is really kind of silly ;-)
forget what you need to know and the entry will be terse and assume so
many things. When a beginner documents something it will be just what
another beginner will need, down to the "obvious" things that
experienced programmers take for granted and assumes that everyone
knows.
Remember that an experienced programmer will probably skip the
documentation and go straight for the source code, so as long as the
source code exists then the documentation in perfect as far as an
experienced programmer in concerned.
What constitues good documentation depends on your needs. The OP is a
beginner and therefore wants beginners documentation, as such the
documentation written by another beginner would be ideal.
Colin Law
date_select helper docs when I was only a short distance into the
learning curve. I had a problem using the method and was helped out
here, at which point I improved the docs so that, hopefully, no-one
would have the same problem that I did.
Colin
Robert Walker
> PHP
> people have. that will surely increase number people who want to learn
> and
> use Rails.
we in the Ruby and Rails communities really want to end up in a
situation like PHP, where the documentation is great, but is notorious
for harboring some of the worst code on the web?
Maybe the barrier to learning Rails has some advantages. Those in the
Rails community tend to be more opinionated than certain other
communities, but as a side-effect of that the community is filled with
people obsessed with beautiful code. People that are willing to overcome
a steep learning curve and not be hindered by minor things like less
that perfect documentation.
Again here is that comparison of language docs and framework docs. I'll
put this challenge to you. Show me where the Ruby (NOT RAILS) docs are
any less complete than the PHP docs. That's the only fair comparison
here.
I mentioned in an earlier reply to this thread that Rails is larger in
scope than PHP (or Ruby for that matter). I did also notices a reply to
that where someone when out counting LoC to counter the statement. They
clearly took my statement out of context, so I'll clarify.
Here is a list of just a few features Rails provides:
- Object Relational Mapping (ActiveRecord)
- Routing
- Rack middleware
- Model-View-Controller (MVC)
- Validation
- The asset pipeline (including cache busting techniques)
PHP, like Ruby is just a programming language. Programming languages are
relatively static. Practically everything they provide are intended to
be used by "regular" programmers in their day to day work.
A framework like Rails is different. Rails is not a language, but rather
a collection of objects that provide solutions to problems in a domain
(a.k.a Design Patterns).
There are parts of it that do not require the same level of scrutiny in
the docs as other parts. Take ActiveModel for example. This particular
group of objects are not intended for direct use by "regular" Rails
developers. Instead it provides an abstraction that can be used by
veteran programmers that wish to subclass ActiveModel to do some more
advanced things. These developers typically don't need the same level of
documentation as others may. It would be a waste of time for them to
write documentation intended for developers who also don't need it.
Don't misunderstand me! This is not about intentionally leaving stuff
undocumented. It's a matter of priority and resources. It is still, and
will continue to be my view, that tremendous effort has been put toward
helping people learn Rails. The Rails guides are, for the most part,
fantastically written. I know, I've read them, and often referenced them
to help answer people's questions on this very forum.
Many of the complaints and frustration I've seen posted on this thread
feel like an insult to the wonderful people who gave their personal time
freely to write those docs. Some of these guys I know personally.
There are some things in life that are hard to learn and even harder to
document.
Along with Ruby on Rails and Java, I also developer iOS apps. I see many
of the same sorts of complaints about that documentation as I see here
about the Rails docs. It is very much the same situation. The stuff that
the Cocoa Touch framework provides is tremendous in scope. There are
literally hundreds, if not thousands, of docs on the iOS SDK framework.
About, two of which cover the language (Objective-C) used to develop iOS
apps. So again the language is considerably smaller in "scope" than the
framework using the language.