Stop developing Rails!

Rails
61

The number of replies and level of invective here I think does equate to
“where there’s smoke, there’s fire”. I bought the books and read this
list
for quite a while, worked through the few tutorials out there and just
played around; BUT, I only did that on the 4th or 5th go around after
the
buzz around the framework was almost deafening. I ignored it and went
back
to PHP the first 3 or 4 times because I couldn’t find the good 50,000 ft
view/introduction to review.

I don’t begrudge anyone for making a buck, and selling the documentation
(in
the form of AWDWR) I don’t find unseemly but it does/will slow adoption
and
critical mass.

As others have said, I too believe that good ‘free’ documentation will
eventually emerge, it just takes time and someone that wants to Shepherd
it.

Perhaps it’s not a direct comparison, but consider how easy the PHP docs
are
to use … want to know about something … type
PHP: Manual Quick Reference up comes syntax, description and user
annotated examples; an RDOC API
dump is nowhere near as nice.

We’ll get there someday, till then you have to have faith it’s worth
learning and buy the book(s).

62

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.

63

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

64

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

[email protected] wrote:

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?

No one said that, and I never implied that. Reread my posts please, I
never indicated either of these things.

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.

I have not seen anyone say or imply this either.

By denying the online lit needs work
you’re implying that you don’t want to teach people how to fish,

I am not denying better documentation would be useful, and I have not
seen anyone say that. The closest thing I’ve said in
relationship to this:

“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.”

If you like to code with people who don’t understand something and don’t
take the time to learn it (they just copy/paste it
without putting much or any effort to learning how it works) then you
are certainly in a different mindset of programming as a
craft then myself.

instead you prefer answer the same question here over and over and over
and over.

Yes, people who don’t take the time to learn how something works are not
people I would spend alot of time trying to move into the
ruby / rails community. People who want to take the time and learn how
it works but need guidance along the way, those are the
people I will fend for.

Please do not confuse the belief that programmers should put time,
energy and effort into learning their craft, with the mentality
of a l33t-ist. They are completely different.

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

Java has way too many books at Barnes and Nobles. So does .NET. It takes
up too much space for good books on other languages.
Thank goodness for Powell’s Technical Books!

Zach
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.3 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFFT6S/Myx0fW1d8G0RAiccAJ94Uc2LV2gLuJmuVF6l25+bid7d2ACfT87M
hgo0HxTtRxOwbFcNsXNVE7c=
=ocom
-----END PGP SIGNATURE-----

65

Oh how I would LOVE a docs system for Rails (or Ruby for that matter)
similar to php.net.

66

On 11/6/06, [email protected] [email protected] wrote:

Oh how I would LOVE a docs system for Rails (or Ruby for that matter)
similar to php.net.

I suspect the Ruby and Rubyonrails docs folks have never used the PHP
manual much… so they just shrug off this sort of remark as a
non-important comparison. I understand their point of view and why
they may have it, but then they aren’t the ones spoiled to using the
best manual in the world either.

I’m sure things will get better over time. Meanwhile you can always
buy some books like I did. shrug

–
Greg D.
http://destiney.com/

67

http://www.railmanual.org/ and http://www.rubymanual.org/ are open and
ready for your use. I’m not sure many people use them though…

–Jeremy

68

A couple of things:

  • If you see Wiki spam, please help us all by backing out until the
    real page reappears.
  • If you ask a loosely formed question of Google, you can expect to
    be awash with random hits. Let’s say the problem you were trying to
    solve was “hmmmm, I want to replace something on the page and I
    forget the exact function name.” Typing “rails rjs replace” provides
    a number of great hits right up top. Just narrowing the search makes
    a world of difference.

Give it a try.

69

What gets me is that if you want to do something clever, quite often
the documentation trail just peters out. Take generators. Code
generation is incredibly useful, but I’ve been searching for ages
trying to find out how the deeper parts of the system work.

The only way I found to do it was to take apart an existing generator,
but I got lost in a tangle of Rails features with no idea of the
philosophy behind them. (obviously, most other generator writers had
left well enough alone…)

Worse, the further I got, the less documentation there was. It came
down to ‘Look at the code’ or even ‘This class exists, but I won’t tell
you a single thing about it.’

I’m getting there, but it’s a struggle. It shouldn’t be a struggle.
Code generation should be a rapid task to make a slow task faster. I’m
spending longer writing generator code that I’d spend doing it by hand.

Seriously, if Rails is to be taken seriously, every feature should be
documented - if only briefly - by the people writing it, as they write
it. It’s called ‘good programming.’ Those little nuggets can really go
a long way towards giving a programmer an idea of what’s going through
the mind of the framework developer - and thus the correct way to use
the features.

It’s interesting how the PHP docs have lots of comments but the Rails
docs don’t. I think there are a few reasons.

1: Leaving comments is less hair-raising than editing a wiki, so more
people will.
2: Allowing posting of links leaves the wiki open to spam.
3: Having docs there in the first place encourages commentary -
especially if incomplete or subtly wrong.
4: Having a logical separation between instructions and comments leaves
it open to ‘Hey, look what cool stuff I did with this!’ style posts.
5: RDoc is a great idea on paper, but appears to encourage laziness and
doesn’t seem to inspire enthusiasm or creativity.

In all seriousness, if I were to set up a wiki doc site with comments
as per PHP (not using the RDoc format), who would be up for
contributing?

70

One thing I think everyone needs to keep in mind is that it’s Rails
ONE-POINT-OH (or close to it). PHP is at 5. Anyone remember the docs
at
php 3? Or how many books there were? Not a whole lot.

Also, comparing PHP to Rails is apples to oranges. Try comparing
Trax/Cake/Symphony to Rails. Last time (about 6 months ago) I looked at
Trax, it didn’t have any documentation.

What gets me is that if you want to do something clever, quite often
the documentation trail just peters out. Take generators. Code
generation is incredibly useful, but I’ve been searching for ages
trying to find out how the deeper parts of the system work.

Take PHP extensions… last time I looked (maybe 1.5 years ago) it was
very “look at the code for examples”… and seems to still be.

Seriously, if Rails is to be taken seriously, every feature should be
documented - if only briefly - by the people writing it, as they write
it. It’s called ‘good programming.’

That’s true and I won’t deny it, but remember that it’s 1.0. PHP has
been
around for what… 8-9 years? Perl even longer. It’s going to take
time…

And i bet the moment core stops coding and documenting everything folks
are gonna be upset that their bugs/feature-enhancements whatever aren’t
getting done :slight_smile: You just can’t win :slight_smile:

In all seriousness, if I were to set up a wiki doc site with comments
as per PHP (not using the RDoc format), who would be up for
contributing?

Seriously… I wouldn’t. Why? It’s yet another site I’d have to check
for documents… Until it’s added to the official rails docs, I
wouldn’t
bother.

Back to lurking…

-philip

71

Hi Andreas, the ‘blank?’ is explained on page 238 AWDWR 2ed (PDF).

Good luck,

-Conrad

72

I might be insane, but I find the official PHP documentation and the
official Ruby and Rails documentation to be pretty much on par. I
really liked the .NET documentation back when I was using it though.

I do agree (minus some of the attitude that has been accompanied with
this thread) that it would be really nice of Rails had better
documentation. I don’t think that it is up to the core Rails
developers necessarily to provide it. There are a lot of developers
that know Rails more than well enough to write good documentation (I
know I would be able to).

-carl

73

Hi, I guess that you meant

http://www.railsmanual.org

In any case, as a new person to rails, I feel that I have enough
information to get things done within Ruby and Rails.

-Conrad

74

My programming experience is about 1 year of PHP, self-taught using
only web resources, and Atari BASIC back when the language was a
little cartridge you plugged into the computer. I’m about as close to
a blank slate as you can get, here, and I had little trouble picking
up Ruby/Rails.

When I decided to try Rails (saw the video, like everyone else) I got
online and started looking around. The old ‘pickaxe’ book is free,
taught me quite a bit of Ruby. Then there was the ‘Rolling with RoR’
and ‘4 days’ tutorials. Both Ruby and Rails API are online, and
though they aren’t optimum (all I have to compare them to is php.net,
which rocked) the info is there. I started writing simple apps,
case-studies that explored different ideas. I played around in
console and breakpointer. I read hundreds of blog posts.

When I needed more info and I had exhausted the web resources I could
find, I joined the IRC channel and this mailing list, both of which
are archived and searchable. Asking informed questions on IRC got me
polite and helpful responses that led me to more knowledge. Reading
through source code of existing apps taught me a lot, and when I saw
things that weren’t documented elsewhere a trip to the IRC channel
cleared it right up.

After 2 months I felt comfortable enough to convert my PHP sites to
Rails. This took a couple of weeks, and gave me the confidence to try
bigger things. I showed a couple of people what I had been working
on, and got some contract work. Only after I had received the
up-front money for the contract did I buy the Agile 2 beta PDF and
Rails Recipes.

So what I want to know is this: given my first-hand experience of the
dismal state of Rails documentation, how is it that I am successfully
doing contract work while other people in this thread are ranting
about how hard it is to learn Rails? There are some bitter people
venting in this thread, and I’m finding it hard to see their side of
the situation. It looks to me like some people want their new and
different language to be as well presented as the old and dusty
languages they know, and are (irrationally) upset that this isn’t the
case.

If you’re that unhappy, you basically have 3 options:

change the system (“be the change you want to see in the world”), or
change yourself (the observer is part of the equation, too), or
leave.

  • foobario
75

Anyone find it funny that “Bob” hasn’t responded again after 70 posts?

The only problem with Rails documentation I’ve had is when I’ve been
told of
some obscure or advanced feature but can’t remember exactly what it was,
but
that’s to be expected with most libraries.

Jason

76

ok maybe we spend too much time discussing in mailings lists and not
enough
time actually coding or setting up helpful ressources

On 11/7/06, Jason R. [email protected] wrote:

and ‘4 days’ tutorials. Both Ruby and Rails API are online, and
things that weren’t documented elsewhere a trip to the IRC channel
dismal state of Rails documentation, how is it that I am successfully
change the system (“be the change you want to see in the world”), or

–
Heri R.
http://sprinj.com

77

Bob wrote:

… and try to write some documentation
It is completely unusefull to develop, develop, develop without
documentation, tutorials etc…

This interesting thread has given me a change of heart on this issue.
When I first saw the thread I thought “Amen brother!”.

Then I read some of the replies and started using some of the searchable
references that were mentioned and came a way feeling much better about
the current state of the docs. One thing I think would be a
horrendously useful addition to all of this would be a wiki-like site
that has example code for every imaginable little part of a Rails app.
Copy, paste and modify is how I’ve been programming for twenty years.
Right now it’s hard to find a good source for the first step of that
process. My own first attempts form the majority of it, which means I’m
scraping the bottom of the barrel most of the time.

Finally, I would like to leave you all with a new MasterCard commercial
that sums up my current feeling on the basic topic of the thread:

Way cool programming language called Ruby $0
Even cooler web application framework $0
Finally not being the odd man out with a Mac priceless

jp

78

I am still here, Jason R.

Because someone before mentioned http://www.railsmanual.org, I opened
this page, , and because I am a curios guy, I wanted to know what
reverse_each_port() is about, and opening
http://www.railsmanual.org/class/TMail%3A%3AMaildir/reverse_each_port/1.1.6
I can see the source of the method. I also find this very useful info,
the method begins at the line 357, in file mailbox.rb. I think it’s very
good that the author didn’t fill the web page with some unneccessary
comments about what this function does.

I think all of you agree with me: looking at the source code of
reverse_each_port() at http://www.railsmanual.org, we all can say that
rails is, undoubtedly, an OPEN SOURCE web framework.

Jason R. wrote:

Anyone find it funny that “Bob” hasn’t responded again after 70 posts?

The only problem with Rails documentation I’ve had is when I’ve been
told of
some obscure or advanced feature but can’t remember exactly what it was,
but
that’s to be expected with most libraries.

Jason

79

On Wednesday 08 November 2006 01:55, Bob wrote:

I think all of you agree with me: looking at the source code of
reverse_each_port() at http://www.railsmanual.org, we all can say
that rails is, undoubtedly, an OPEN SOURCE web framework.

Actually, we all new that already. Now, if Rails was a closed source
framework, how much would you be willing to pay for it?

Michael

–
Michael S.
mailto:[email protected]
http://www.schuerig.de/michael/

80

I just tried to be ironic…

Michael S. wrote:

On Wednesday 08 November 2006 01:55, Bob wrote:

I think all of you agree with me: looking at the source code of
reverse_each_port() at http://www.railsmanual.org, we all can say
that rails is, undoubtedly, an OPEN SOURCE web framework.

Actually, we all new that already. Now, if Rails was a closed source
framework, how much would you be willing to pay for it?

Michael

–
Michael S.
mailto:[email protected]
Michael Schürig | Sentenced to making sense