Hmm, the comments are cool I guess, but I’m not sure I see them being that useful besides as author feedback. It’s not that obvious if clicking on the comment thing is going to get you any reader-useful information or not.

That said, it is clear that they’ve put a lot of thought into the architecture of the book. More of this in Ruby please!

For an example of useless comments in place of strong documentation, look no further than the PHP manual.

as Guido has said – the django guys really ‘get’ open source. they take their time with releases, provide helpful docs and show respect to their users (by sharing their security policy for example).

The rails team don’t seem too be concerned with any of these things sadly. Rails has inherited the same blatant disregard for docs as ruby. Fancy finding out whats new in ruby 1.8.5? Just go through the Changelog. Cheers, big help.

Anyone know where the source running djangobook is?

The djangobook source is right here: http://www.djangoproject.com/

@ajs: I think yerejm actually means the source of the application for djangobook.com, not the source of the framework. I may be mistaken, though…

RubySpec! It could be the definitive free doc, if we all pitch in and help fill it out! Even Matz has made some edits…shoudn’t you?

The problem I have with RubySpec! is that it is a wiki which makes it easy for spammers to spam. I also think we could make something that looked much nicer.

ajs+lukfugl: Yeah, I’m interested in the application source for the djangobook site.

Thanks for the nice words :)

MenTaLguY: you’re completely right that the comment system is designed primarily for author feedback. Our goal is to release a book that’s as useful to the Django community as it can, and so channeling discussions into a form that helps improve the book was the primary goal.

yerejm: I’m working on cleaning up the source for a public release; it’s very much a first cut and as you might except that means I’m not toally happy with it yet. Stay tunned, though—it’ll be up soonish. I’ll say, though, that most of the coolness actually comes from Docutils (http://docutils.sf.net/); being able to transform our book source into any format we can dream of really, really helps.

Thanks again!

Rails guys have, sadly, been a touch too worried with tech that end users don’t care about (i.e. REST ). I guess it’s fun for geeks though.

Getting good, coherent, and open documentation of Ruby/Rails online would be a huge step forward. A lot of the time, the docs’ most useful feature is their link to the source. If we could get better documentation collected in one place, the whole community would benefit.

Yeah, what ever happened to these funds that were raised in order to improve Rails’ docs?

“Rails guys have, sadly, been a touch too worried with tech that end users don’t care about…”

Heck, if that’s the plumb-line, why don’t we all just start writing our web apps in Assembly?

I second DerGuteMoritz’ question.

meekish + klondike - one thing they've started doing is http://rdoc.caboo.se/doc/

You can inline edit the RDOCs for Rails, and the changes are then submitted as patches automatically. Patches can then be voted for by other ppl who’ve submitted patches.

Click the Edit button on any page to see the snazzy RDoc monkey.

Unfortunately, oh _why, we care, but we don’t give a crap. Thats the problem. Caring but not doing a thing about it when push comes to shove.

Good work Django.

As for Ruby – I’m happy with our books (Agile Web.. and Recipies), and they mostly suffice for my needs. But it will be interesting to see the end result of the Django book.

This is a good example of the learning / exchange / competition between Django and Rails. I really like it, as it helps both frameworks improve and mature. I’m happy for the cooperation between DHH og Adrian Holovaty and that flamewars are avoided. Let’s keep it that way.

Hey, thanks for the nice words about our book!

For those of you (MenTaLguY, noodl) who are concerned that the comments system is hard to follow or results in unuseful comments, I’ll echo Jacob’s explanation that they’re intended for the authors, being very targeted discussion of particular points in the book. But also, note that we’re actively rolling the suggestions into the text itself and deleting the comments along the way, which is a key difference between our text and, say, PHP ’s. We do the same with the official Django documentation.

This is the one thing that Rails is lacking.

I completely agree that something along the lines of DjangoBook (congrats Adrian and Jacob) is needed for Rails. RubySpec! looks good, but we need something for Rails too. Wiki.rubyonrails.com doesn’t cut it; Railsmanual.org is a good start if we added more examples to the API (and clearer explanations of which options each method takes), but it doesn’t give the clear understanding of the framework that the Agile book does. (The Agile book is great and a must-read, but it gets outdated as Rails progresses.)

I’m compelled to point out that the open source Django Book is not only a testament to Adrian and Jacob “getting” open source (they do, great work guys), but also to Apress “getting” open source. This isn’t the first time they’ve open sourced a book like this, and I think that’s pretty kick ass of them.

Dr Nic:That rails app didn’t cost anything to set up though, so the question still remains, wheres the money? :)

Call me crazy, but I’ve always thought that the lack of quality free rails documentation was intentional.

It reminds me of a pyramid scheme.

The lack of documentation drives people to purchase the books (or attend the conferences) written (or given) by the people at the top of the pyramid.

Then again, I could be wrong.

Crazy, I’m with you on this. But it is a little bit more than just the sale of books. I know fanboys and sycophants are going to jump all over me for saying this, but it is clear as day.

Rails team has not released a SINGLE screencast since they have achieved critical mass. It seems everyone is trying to make a quick buck via short courses or paid screencasts etc.

Also, the more there is a general sense of confusion about rails code, and the more obfuscated it is, the more consulting gigs the top tier developers are going to land. Or so the logic seems to be.

Zope died a miserable and horrible death because of almost exactly the same reason. It used to be a phenomenon not unlike Rails, and it is just a bit player now. The main zope people are still getting gigs, but the thousands that wasted their time with their self-defeating strategy were left out in the cold holding the bag. Zope core had a gigantic chip on their shoulders and the marketplace cut them down to size.

But this is short sighted and the bottom is going to fall out of the rails market if the main people keep grubbing away at the short term cash. This is cynical and self-destructive.

Perhaps this is why there are now ruby/rails book bundles available on various torrent sites. A backlash against the greed of some people perhaps?

just my O.

I hate to spoil the conspiracy theories, but the reason that there isn’t more Rails documentation is because it takes a LOT of time to write good documentation.

With all respect to Holovaty and Co., they have a deal with a publisher and are being paid to write the book. Of course, this usually means that the publisher takes 90% of the revenue and gives the authors 10%, but they still have a vehicle for selling the book once it’s done.

The fact is that the free market actually works. Money is a pretty good motivator, which explains why there are so many books on Rails being published right now and even more on the way. The “quick buck” people are making on documentation takes days, weeks, or months to produce.

There is no free beer. Any open source code, documentation, or entertainment that you download comes at a cost to the person who took time to write it, serve it, and advertise it. They are subsidizing your education.

Even if we loot Mr. Kaplan-Moss’s publishing & commenting system and use it for Rails (which I think we should do…we’re already using the Python-powered Trac for bug tracking), someone will have to write the actual docs. Many of the comments on the djangobook site are mere cheers or boos…the real work is putting that into a coherent document that people can actually learn from.

Can we count on Crazy and Kooky as the editors for this new project?

Coherent documentation doesn’t exist because there is no “official” support for it. There is no ‘conspiracy’, it is just that the rails clique prefers things be done in which they or their friends get paid. simple.

no docs means a general state of confusion, which means corporate customers will ask those who are “in the know”, and guess who is in the know? the rails core and a small group of other people.

If people could figure things out themselves why would anyone pay top money to people who can charge high rates specifically because rails has such shoddy docs and such shiny hype :)

if you can get a rails site to get up and stay up for more than a month, I’d be happy to “edit” it (as long as the clique approves it I suppose?). Most rails doc sites die horrible deaths a week after launch. None of them can handle a decent load (like, say, a 100 concurrent users?) without barfing all over themselves, and at that point, the kind soul who was managing the site has to say goodbye because scaling up to accept even the size of rails community (say 10,000 ??) is a costly prospect which no run of the mill good samaritan can afford.

This leaves the big players, who have no interest in maintaining these sites for reasons already explained. :)

if you can get a rails site to get up and stay up for more than a month, I’d be happy to edit it

I’ll take you up on the offer. I just bought railsbook.org and will order a VPS tomorrow.

topfunky: huzzah! Please let us know here when it’s up!

Good going topfunky. Now, if only the caboosers could keep their http://rdoc.caboo.se/doc/ site up.. ;-P

Let us see if Rails has the potential to create a railsbook site which is better looking and more functional than the one created by Django

It must just be me, but I haven’t had a problem with Ruby or Rails documentation. The API ’s for Rails and Ruby combined with the Rails wiki and the myriad tutorials online have been plenty for me. I started learning Ruby and Rails concurrently at the beginning of this year, and those online resources plus the Ruby book (second edition), Agile… Rails, and the Ruby Cookbook have let me write several Rails apps and Ruby scripts for my job.

As a side note, the cool AJAX comment system comes from the great work Jack Slocum is putting out here:

http://www.jackslocum.com/yui/2006/10/09/my-wordpress-comments-system-built-with-yahoo-ui-and-yahooext/ http://www.jackslocum.com/yui/2006/11/04/033-beta-2-basicdialog-yahooextview-and-more/

Sorry but I’m not interested in the whole documentation debate. I have been able to learn and deploy applications for over 2 years now using the documentation available. I know it can/should be better but I am not going to complain until I am ready to do something about it.

AEM

j`ey: The doc money is right here waiting for someone to ask for it. No-one’s stepped up.. seems like people love the whining but not the fixing. I’ve asked 70% of the published ruby authors out there (at rubyconf, and on irc) and they’re all either “I don’t know rails well enough” or “I’m kinda busy with other things” or “I’ll get back to you”. So, the money sits.

The rdoc project is still in development—it hasn’t launched yet. We’re working on it. Please send qualified help! http://svn.caboo.se/rdoc2/

Yeah, it stinks that the Rails guys are putting in features and functionality. They should be doing more documentation. C’mon, they are writing their own applications to put food on the table, and supporting a framework that others can use if they choose.

Don’t like the state of documentation. Do something about it. In my experience, Rails is not an intellectual framework. People use it because they can get stuff done and for a lot of developers that means documentation falls by the wayside.

When something new comes out in Rails, I can usually find a handful of useful blog posts that I can use to pickup the functionality. Yeah, it’d be nice if someone had it all in one place. I’m really looking forward to therailsway.org being built up. Best practices would be very helpful.

The conspiracy theories are especially precious considering the fact that none of the Rails core team members are available for consulting services. So is the theory that we in the core group slave away to make some other “top tier” (however that’s defined) developers rich for the blue in their eyes? WTF ?

The slowdown in core-produced documentation is very simple: Time. We have less of it and it’s become more valuable for most of us, so we’ve accepted the constraint that the core team predominately works on moving the state of the art forward, while others produce documentation and training for free and profit (as they see fit).

And of course, like bty says, nobody owes you anything. If you don’t like the way the world spins, please be an agent of change on your own accord. Stop whining, start producing.

Oh boy, this is a fun discussion!

• The Django book is a great model
• Rails doc really does suck
• I haven’t done anything to move it forward, and I’ll bet 98% of you haven’t either, because
• It’s a pain to create and submit doc patches, and I’ve got other stuff to do like everyone else

The Caboose site is the first one I’ve seen that might really help move the docs forward.

I’m going to make it my primary Rails doc bookmark. Then whenever I look up a method that not or poorly documented, I’ll try to hit Edit and add some documentation to it. Shouldn’t take that long, right?

If everyone did that, we’d be a lot further along.

Then we can start tackling the mess that is the Wiki!

i refer all to: mr yegge

these are cultural differences. python has very good docs, and that comes built-in: python.org/doc

i’ve used python for about 5-6 years—but never needed a book…

i just started learning ruby. ordered 6 books from amazon.com. avg around $25/book—not bad at all!!

while python has docs that’s come built-in, ruby come with docs that you gotta buy — but ruby docs (like programming ruby — i’m 128 pages into it) are awesome — don’t think there is a python equivalent to that!! daveT and andyH—you guys are friggin’ awesome.

• so dear rubists
• and ‘bout to be rubists;
• don’t fret,
• for all the docs you need,
• comes at a price of $25/piece.
• but that’s not all you get!
• with it you get the wisdom
• of daveT, andyH, and mr black
• and most of all
• our dear DHH

The End.

About the Caboose site: I wonder if it might be more accessed if it were searcheable, like railsmanual.org. It’s must faster to find something that way.

There neither beauty nor joy in not caring.

My point is that DHH or others in positions of influence DO NOT stress documentation like they stress buzz-word du-jour. There were hundreds of entries in the railsday contest and almost 95% did not bother to include a simple readme file.

Did someone take them to task for it? NO!! All of the entries which did not bother to document should have been disqualified!

It is symptomatic of an asinine attitude towards your users, and very typical of developers in the rails community, fostered by an un-realistic “bad boy” image which DHH and the rest of the core are trying to project for some lame reason.

What good is it that you write thousands of lines of so called tests, while you fail to write a one page readme file? What does it say about your philosophy towards the endusers? as you go on crowing about sappy new-age buzzwords?

And DHH you are wrong. If you come trumpeting your framework, and claim “productivity” this, and “joy” that, then YOU DO OWE the community which is following you for their own reasons, not because you are some kind of meshia (your delusions of grandeur not withstanding).

An open source project is an implicit contract. There is no free ride for either party. You don’t get to abuse us, after riding a wave of popularity based on hype (some would say) and we don’t get anything for “free”, we give you our time and support and legitimacy via adoption, and we expect some frikking proper documentation!

My advice: Stop promoting an atmosphere of generally rude behaviour. Stop talking down to everyone! You have only seen the fall-in, you haven’t seen the exodus (just yet). And it’s not going to be pretty when people DO start to say FUGHETTABOUTIT .

President Bush would call this the Blame Game and he would not get involved.

The broken vase theorem might be applicable too :)

zerohalo: I find the command-F in Firefox works just fine for searching the caboo.se docs. I will also make it my primary doc bookmark, and let’s get those edits rolling.