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

rubyonrails-talk
21

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 Jones

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.

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

25

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.

26

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

27

"scope" != "LoC"

28

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

29

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.

30

Robert Walker 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.

31

Kevin McCaughey wrote in post #1058376:

Robert Walker 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 Walker wrote in post #1058397:

Kevin McCaughey wrote in post #1058376:

Robert Walker 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".

33

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.

34

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.

35

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

36

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

37

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.

38

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

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

40

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: