Karthikeyan A k wrote in post #1058413:
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.
But, do we REALLY want that? I hate to have to word it this way, but do
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.