Stop developing Rails !!!

"The worst thing is that you also need to be very familiar with OSx
Unix
commands and that you need to compile everything"

No offence but I find it slightly annoying when I read this. You're
meant to be a programmer for crying out loud! Why do you need a
graphical UI to hold your hand? If you don't know your way around a
Unix terminal - learn!

No programmer worth their salt should be afraid of getting down and
dirty with the terminal, or learning how to do so.

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?

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