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

Rails
21

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,

Bringing up Kohana as an example is particularly silly, since you could
practically use the Rails API docs as a reference to use it. For
instance:

and

(from the previous release of Kohana, btw) These two sections are nearly
identical, and they’re not the only ones. This isn’t plagarism - it’s
just
the natural result of a framework deliberately constructed following the
Rails pattern.

Back to the topic at hand - are you planning to do anything BESIDES
whine
on this forum / mailing list? At this point, I’m not even sure which
particular missing documentation you’re using as an example -
method_missing is clearly defined in the stdlib docs, and even if it
wasn’t
this would be the wrong list to discuss adding it…

–Matt J.

22

I mean seriously Sergey, complaining about the state of rails
documentation while refusing to contribute to it makes you come across
like an entitled little snit.

23

Hi Sergey, I think you might be interested in the docrails[1] project.
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: Ruby on Rails — What is docrails?
2: http://github.com/lifo/docrails

24

Certainly, I will be glad to help! As soon as I will acquire experience
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. And also, documentation uses as reference manual for more
skilled developers.

Very much I hope that developers of the Ruby on Rails will take into
consideration my notes.

25

According to ohloh.net, rails has about 250,000 lines of code, while
Ruby recently eclipsed 1 million lines of code.

http://www.ohloh.net/p/rails

http://www.ohloh.net/p/ruby

26

On 25 April 2012 15:36, Kevin B. [email protected] wrote:

On Tue, Apr 24, 2012 at 4:10 PM, Robert W. [email protected] wrote:

Languages are MUCH smaller in scope than frameworks.
According to ohloh.net, rails has about 250,000 lines of code, while
Ruby recently eclipsed 1 million lines of code.

“scope” != “LoC”

27

On Tue, Apr 24, 2012 at 4:10 PM, Robert W. [email protected]
wrote:

Languages are MUCH smaller in scope than frameworks.

Well… Rakudo Perl is much larger than the Parrot framework it is
built on. And pretty much any language or compiler you create with
LLVM/clang project will be smaller than LLVM itself.

–
Greg D.

28

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.

29

Robert W. wrote in post #1058190:

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.

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.

30

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

31

Kevin McCaughey wrote in post #1058376:

Robert W. wrote in post #1058190:

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.

Hum, It so happens that I know a lot of people that get a lot of really
cool stuff done in Rails. This leads me to the think that maybe the
problem lies somewhere besides the “poor” docs? Just a thought.

32

Robert W. wrote in post #1058397:

Kevin McCaughey wrote in post #1058376:

Robert W. wrote in post #1058190:

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.

Hum, It so happens that I know a lot of people that get a lot of really
cool stuff done in Rails. This leads me to the think that maybe the
problem lies somewhere besides the “poor” docs? Just a thought.

You don’t consider that mass of people which stopped and aren’t become
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”.

Only it is not necessary to argue that professionals with success can
work with source codes. Professionals appreciate the time, they want to
work with comfort and it is productive - good documentation too is
necessary to them. Good reference manuals on classes, methods,
parameters of methods are necessary.

33

I strongly feel Rails community should have a good documentation like
PHP
people have. that will surely increase number people who want to learn
and
use Rails.

34

Kevin McCaughey wrote in post #1058376:

STOP! Stop adding bits on and go back and tidy up the mess.

Thanks! Very sensible thought! Well formulated.

35

2012/4/26 Karthikeyan A.K [email protected]:

I strongly feel Rails community should have a good documentation like PHP
people have. that will surely increase number people who want to learn and
use Rails.

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?)

36

I can sympathise with Kevin and find his experience similar to my own.
Whether his recommendations make any sense … I’m not so sure …

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: [email protected]
[mailto:[email protected]] P vegne af Kevin McCaughey
Sendt: 26. april 2012 00:04
Til: [email protected]
Emne: [Rails] Re: To developers of Rails: Feeble documentation -
weakness of Ruby and the Ruby on Rails (2nd editi

Robert W. wrote in post #1058190:

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.

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.

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

–
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 [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/rubyonrails-talk?hl=en.

37

On Apr 26, 2012, at 1:36 AM, Michael P. wrote:

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?)

Nearly every frickin’ time I look something up. Rails docs are really
awful compared to every other framework I’ve ever used. You ask for
specific examples, but in this case that’s almost a misdirection.
Documentation of methods should cover every argument and option, and
they just do not. The guides are pretty good; the references stink.

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 R.
[email protected]
http://www.elevated-dev.com/
(303) 722-0567 voice

38

On 26 April 2012 14:13, Scott R. [email protected] wrote:

On Apr 26, 2012, at 1:36 AM, Michael P. wrote:

Again… which bit of documentation needs to be better

Nearly every frickin’ time I look something up. Rails docs are really awful
compared

Now, this is where I’m flummoxed, because I just don’t find that. I’ve
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.

39

On Apr 26, 2012, at 7:43 AM, Michael P. 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 :wink:

–
Scott R.
[email protected]
http://www.elevated-dev.com/
(303) 722-0567 voice

40

On Apr 26, 2012, at 7:43 AM, Michael P. 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.

It’s really not style that bothers me; it’s incompleteness.

–
Scott R.
[email protected]
http://www.elevated-dev.com/
(303) 722-0567 voice