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
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
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