Stop developing Rails !!!

You are severely disturbed if you think that Google and the (current)
API docs are all you need to learn Rails. I don't think API docs are a
good place to point newbies; I think RDocs are great for people who
"get it" but need a little nudging.

I agree with the OP. Rails' docs suck for over half of the people who
are going to come to Rails. This is why we have a lot people asking
questions on the mailing list that could/should be answered by quality
documentation. I'm working on trying to fix this documentation
conundrum that with my books, but I'm only one person and the
featureset is so fluid that it's hard (at this point, impossible) to
keep up.

I think it's kind of ridiculous to ask someone to pay $40 for book to
be able to use your framework because your documentation is terrible.
I really hope that the documentation drive takes off and produces
something useful.

I apologize for the rant.

--Jeremy

Though it's not ridiculous to pay $40 for a book that will teach you to
use a framework that has less than ideal documentation, if buying that
book and using that framework might save you more time *per day*, and
therefore make you more money *per day*, than the book will cost you,
assuming you charge about 1 book/hour. :slight_smile:

Right, but many poor students like myself can't shovel out that kind
of money at every little piece of tech that flights our fancy. If I
can't tell that it's going to save me money (i.e., by using it in a
real situation), then I'm not going to shovel the money out.

Fortunately, I've been doing web development for a while, so I picked
up on enough basics to know that Rails could save me a butt load of
time. But I know other people who have been doing app development for
a while or don't know anything about web development who refuse to
pick up Rails because they don't see the benefit in it, _mostly_
because they don't understand enough about it to put it into use and
gauge it's usefulness.

--Jeremy

On documentation: I’ve found the following CHM version of the Rails API to be very helpful. Quick and easy to search. View with xCHM on *nix.

http://delynnberry.com/2006/10/16/rails-chm-documentation-version-1-1-6

If you want to evangelize rails then do so, but don't push for the rails core team or DHH to write beginner level documentation

I'm not pushing the core team; they're too busy writing code (at least
they should be! ;). I'm not really pushing anyone. All that's needed
is an open, introductory text. It shouldn't be this hard, especially
since the community invested thousands of dollars in something that
hasn't seen the light of day yet (even though i'm sure they're working
on it).

just to open the eyes of people who are too stubborn to check it out.

That's a completely false blanket statement. I've worked in computer
science departments and companies where people were Java and PHP
whizzes, but couldn't understand the whole concept of architecture
patterns or HTTP and web applications. I wouldn't say they're
stubborn, they just need more cottling. It's stupid and arrogant to
say, "Well if they don't get it, they're just stubborn."

You say you a poor college student, I am sure you've made worse decisions with your loan money then spending $20 for the PDF or
$40 for the book.

Heh, yeah. I'm sure _single_ college students probably do, but being
married and having to actually pay bills with a monthly income that
can be described as dismal (i.e., like half the poverty level), it's
very difficult for me to release that much money for something like a
book about a web development framework.

In a way I like the lack of beginner level documentation. I know it limits the growth of Ruby and/or Rails, but you at least get
people who you know actually understand the langauge/technology and not those who just know how-to copy/paste.

That's just selfish and, really, childish. "Let's keep the stupids
out!" Sheesh.

Again I say, this is the attitude that makes people hate Perl.

--Jeremy

I want to make it completely clear that what I'm about to say is not
meant to be condescending at all, merely a statement of fact and my
observations.

If you live in the United States, or anywhere else in the world that
practices some form of capitalism, you need to understand that lack
of capital is going to bring substantial disadvantages to those with
capital. After all, it's literally the name of the game.

The good news is that if you're willing to risk the $20-40 of capital
and buy the wonderful documentation available, then you should be able
to gain a subtantial improvement in your monthly income that will more
than offset the price of the docs.

Hang in there. Starving student is a difficult role to play. Rails
should be able to improve your lot substantially.

I didn't say that people who don't get it are stubborn. I am weary of people who *don't* want to get it.

But let's be frank here, how many people are like that? Some people
simply don't make the connection between some things; trust me, I
worked as a sysadmin/help desk person for a computer science
department. Some people can write amazing thesis projects that blow
my mind, but can't connect that information with real-to-life
situations. I think it's the same with the documentation. Sure, show
me a recipe book application, but what can those concepts do for me?

I didn't say "Let's keep the stupids out". I am weary of programmers who know how-to copy/paste code from tutorials but don't take
the time to understand how it works.

I fail to see how beginner documentation inhibits that?

This is a blank statement. I am a person, and I am included in the above "people". The attitude and belief that people learn or
try-to-learn a language/framework that they are going to use (or say they know how-to use) is not one that makes me hate Perl (or
any language community).

No. The attitude of "RTFM!" or "If you don't get it you're just
stupid" is what makes people (e.g., me) hate much of the community
around Perl and Lisp and other "elitist" (generalization, I know)
languages. People saying that we don't need documentation to keep
people out who need it are exhibitng that same attitude.

--Jeremy

I understand that, but I also don't see why that has to be the case.
Call me a community or a hippie, but if there is the possibility of
this information being available to everyone, then why avoid it?
Maybe it's not the people trying to learn that are lazy or stubborn
but we the community who are refusing to offer this to everyone.

The good news is that if you're willing to risk the $20-40 of capital
and buy the wonderful documentation available, then you should be able
to gain a subtantial improvement in your monthly income that will more
than offset the price of the docs.

Of course, but the money is just one issue...time is another story. :wink:

--Jeremy

} You are severely disturbed if you think that Google and the (current)
} API docs are all you need to learn Rails. I don't think API docs are a
} good place to point newbies; I think RDocs are great for people who
} "get it" but need a little nudging.

We call those people who "get it" programmers. Google will find you the
first edition of AWDWR which is free for download. That will teach you the
basic concepts behind of Rails (MVC, convention over configuration, app/*
directories, ActiveRecord, etc.). The rest is just the API, which is
reasonably well documented online.

Failing that, there is the source itself. If you understand Ruby well
enough to use Rails effectively, you understand it well enough to read,
comprehend, and even introspect the Rails source code. Of course, many
people are coming to Rails without strong Ruby knowledge; that's fine, and
they are encouraged to buy books and read the mailing list archives and
learn both Ruby and Rails.

} I agree with the OP. Rails' docs suck for over half of the people who
} are going to come to Rails. This is why we have a lot people asking
} questions on the mailing list that could/should be answered by quality
} documentation. I'm working on trying to fix this documentation
} conundrum that with my books, but I'm only one person and the
} featureset is so fluid that it's hard (at this point, impossible) to
} keep up.
}
} I think it's kind of ridiculous to ask someone to pay $40 for book to
} be able to use your framework because your documentation is terrible.
} I really hope that the documentation drive takes off and produces
} something useful.

Translation: Despite having provided this excellent web application
framework into which you have invested many hours of work at no charge, you
suck because I have to pay money for documentation of a quality similar to
that of the framework itself. I am unwilling to dedicate any time, effort,
or money to learning to use this excellent product; it is your
responsibility to spoonfeed it to me at no charge.

This translation is somewhat tongue-in-cheek, but I hope it points out the
absurdity of complaining about the cost of documentation for free (and
Free) software.

} I apologize for the rant.

Accepted.

Incidentally, you should check your local public library (and school
library, since I believe you mentioned being a student) to see if they have
AWDWR. If they do, you have access to the book at no cost. If not, most
librarians (both public and academic) are delighted to get feedback from
patrons on what books they'd like to see. Generally, librarians make
guesses on what to purchase based on their own preferences or what they've
heard from their friends, but can order and have a book on the shelves
within a month if there is a request from a patron (and the book isn't
hideously expensive). Make friends with your librarians; they are there to
help you and the good ones are eager to do so.

} --Jeremy
--Greg

Incidentally, you should check your local public library (and school
library, since I believe you mentioned being a student) to see if they have
AWDWR. If they do, you have access to the book at no cost. If not, most
librarians (both public and academic) are delighted to get feedback from
patrons on what books they'd like to see. Generally, librarians make
guesses on what to purchase based on their own preferences or what they've
heard from their friends, but can order and have a book on the shelves
within a month if there is a request from a patron (and the book isn't
hideously expensive). Make friends with your librarians; they are there to
help you and the good ones are eager to do so.

A lot of libraries can do inter-library transfers as well, which opens it up to just about every library in the country. My sister in law in Hershey, PA regularly gets books from the new york library through her local library...

Someone's gotta have it :slight_smile:

We call those people who "get it" programmers.

Do we? There are a lot of aspects of many programming languages that
I don't understand yet. LISP, for example, blows my mind. It's not
that I don't think I couldn't get it, I just haven't found something
that explains the concepts in terms low enough that a lowly
former-C#-programmer-turned-Ruby can understand.

Same problem here. I've talked to a number of people who just can't
put the pieces together from the free resources available. It's
nothing that's a tragedy, it's just a fact.

Google will find you the
first edition of AWDWR which is free for download. That will teach you the
basic concepts behind of Rails (MVC, convention over configuration, app/*
directories, ActiveRecord, etc.). The rest is just the API, which is
reasonably well documented online.

Are you sure? I haven't been able to find that legally.

Failing that, there is the source itself. If you understand Ruby well
enough to use Rails effectively, you understand it well enough to read,
comprehend, and even introspect the Rails source code. Of course, many
people are coming to Rails without strong Ruby knowledge; that's fine, and
they are encouraged to buy books and read the mailing list archives and
learn both Ruby and Rails.

Right, but I'm sure a lot of people aren't community oriented. They
can learn Ruby from the first edition Pickaxe (I did), but asking them
to join mailing lists and forums because the docs aren't very good
isn't a good thing (in my opinion). Perhaps I'm a shade more
antisocial than most, though.

Translation: Despite having provided this excellent web application
framework into which you have invested many hours of work at no charge, you
suck because I have to pay money for documentation of a quality similar to
that of the framework itself. I am unwilling to dedicate any time, effort,
or money to learning to use this excellent product; it is your
responsibility to spoonfeed it to me at no charge.

Is "spoonfeeding" so much to ask for from _someone_? PHP manages to
do it. Java manages to do it. Python does it. Heck, Django is doing
it. We can't? I'm not criticizing the core team; I'm just throwing
out the fact that the docs aren't very conducive to learning with.

My point: when people like you and others who have posted here just
say, "well if they don't get it from what's available TOO BAD," just
save the keystrokes and help write some documentation so the next time
someone asks a question like that they will either already know the
answer or you can refer the to the documentation specifically.

--Jeremy

None of ours do actually; I checked when I first became interested in
Rails and just checked again. I put in a "request" a while back (a
lot of good those do), but I haven't seen anything of it yet. They
have 5-6 python books, so I'm hopeful!

--Jeremy

If you don't get something and someone explains it to you and you get it, you could also write some documentation for the next
person. That would show your appreciation for the person who took the time out to help you *get it*.

Precisely. :slight_smile:

This all seems quite silly; all I'm asking is why _not_ have good,
free, introductory docs? If someone is willing to do it (which I
would hope they are since we have about $15K sitting in a fund
somewhere for it), then why not do it? The reasons seem to be: people
shouldn't have to be spoonfed, it's not my job, the core team is busy
enough. These are all remedied (hopefully) by the documentation
project.

--Jeremy

I'm just curious...has ever an announcement been made to the end that
Rails should be only learned and used by the few, the proud, the
illuminati? Sorry, man, but in my perception the end users will
ultimately be the judges of the success of the framework. Those of us
who are coming from PHP, Java, or even Py need some guide to getting
around and used to Ruby/Rails. I don't consider myself lazy or a
cheapskate...however, there are times when I DO NEED info
ASAP...i.e...info I can find by googling (sic). It does not have to do
with my logic, arithmetic or RDBMS know-how..it has to do wih the way
that Rails handles some things or events.

With that arrogant and pedantic attitude of, "if you can't find the
answer, tough luck, good ridance," will only alienate people who might
have a thing or two to contribute. The old proverb comes to
mind..."Give a man a fish and feed him for a day, teach him how to fish
and feed him until 2050 or so." By denying the online lit needs work
you're implying that you don't want to teach people how to fish,
instead you prefer answer the same question here over and over and over
and over.

I've yet to hear anyone complaining about too much documentation.