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

[ssr]

On Apr 26, 2012, at 7:04 AM, Scott R. wrote:

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

---

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

[ssr]

On 26 April 2012 16:26, Peter H. [email protected]
wrote:

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.

+1, I myself added some clarification to (if I remember correctly) the
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

[ssr]

On 26 April 2012 15:04, Scott R. [email protected] wrote:

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

No this is the best thing to do. When you are experienced you tend to
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.

[ssr]

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.