The Django Book project is quite interesting and appears to be receiving a fair amount of participation due to an ingenious commenting system.

IMO, the Rails Documentation Project has nothing to lose trying out a similar system.

http://www.djangobook.com

I’ve found the people who have enough knowledge about Rails and who can edit the source to add doc patches are earning consulting money enough that it’s not financially viable (for me or the Doc Project) to pay them to write docs. FYI I was paying $450 USD a day for writing. It just doesn’t motivate people.

We started writing an app that would take documentation patches, which could be voted on, and a bounty or prize awarded weekly of a few $100. Unfortunately providing an interface to horrible, horrible RDOC proved the death of the project. The project is open source. http://rdoc.svn.caboo.se/changesets

Solutions? I don’t have time to work on them, but there’s still about $7k left in the Documentation Project. If “someone” sets up a way to distribute it, it’s there for the taking. As long as it provides documentation within the API.

Finally, a challenge: every few months someone pops up on one of the mailing lists bemoaning the terrible state of documentation. They have some holy fury, then when pressed for specifics, they disappear. So: set me up a bounty system, where you can nominate specific things needing docs, and I’ll pay it. Just like that.

What your describing is very close to what I’ve been wanting to build with coderpath. My biggest problem is I haven’t had the programming chops to actually build the site. The idea with the name coderpath was to help programmers (coder) find their way to becoming a competent programmer (path….hence ‘coderpath’).

I’d still like to see that vision realized. If there’s an experienced Rails developer out there who’d be willing to be a mentor to me, please drop me an email.

I want a site like you’re describing Geoff because I need it!

Seems like you get the same e-mails from the same people as I do!

no one has tried to organize existing blog articles.

This has been one of my “back burner” ideas for almost two years now! JRubyInside.com was going to do it before I got lazy and turned it into what it is now (although it ‘semi’ does it in the categories section). Perhaps I’ll pull my finger out!

For doc… I’ve been a huge fan of GotAPI (http://gotapi.com/ or http://start.gotapi.com/). It aggregates the best API doc sites for various different languages/frameworks.

Great idea, I’m always trying to remember where I saw key posts and end up Googling the same stuff again and again.

A colleague of mine (Chris Haupt) and I have started building a site that will organize blog articles as you suggest, and will have a bunch of original content (and some other cool features) as well. It’s BuildingWebApps.com. We’re in a very limited private beta right now but will be opening it up soon to people who add their names to our beta invite list.

I agree with your insights into why documentation sites tend to languish—if there’s no business model behind the site, the people who build it tend to lose interest after a while. And if you depend on the community for most of the contributions, you tend to end up with some brilliant parts, but lots of cruft, and with very spotty coverage.

The Rails community has created a tremendous amount of great content. It just needs some organization and intelligent (not bulk) aggregation. There’s also a need for more high-quality tutorial content, as the success of Peepcode has shown. Most of the blog posts are written for readers with a pretty high level of knowledge.

We believe we have a business model that will sustain our efforts (which we’re not quite ready to talk about). And we believe that while the community contributions will be very important in time, we will do enough of the work ourselves to get the site to critical mass and keep it updated. We will also actively moderate and edit the site, so it won’t end up as a mess like the Rails wiki.

I’ve been working on the article rating/reference thing with John Athayde. That’s what Pimp My Rails will be, first and foremost. It just had to take a backseat while we scrambled to make the transition to consulting full-time.

I think I’m not being too conservative to say that it’ll ship - with content - end of Oct, early Nov.

If anyone wants to contribute a nice, canonical list of links on a given Rails or Ruby topic, lemme know. :)

I personally believe rails documentation isn’t really as bad as people think it is. The documentation pretty much serves the purpose it is meant to ( reference/sanity check ), but the real problem is, people don’t know what exactly to search for. This comes from hanging out in #rubyonrails way too much and reading rails mailing list from time to time.

So if you have commenting enabled documentation, you run into the same problem I described above.

@PJ : http://www.railsdocumentation.org/book.html is something similar I believe.

I don’t get why it’d be that hard to start and existing documentation project for rails. There’s already a lot of free documentation out there (the code it self), it you could write a scraper that would scan the files and put it into a database you’d at least be equal with the api. Then just tag by where the doc was found, the method name, other aspects. Add commenting, better navigation then you would have yourself a site. Heck, if I had more time I’d knock it out.

Hi Courtenay. You mention a bounty system where you can nominate specific things that need docs.

Do you think http://micropledge.com is the bounty system you’re after? Projects tagged with the same tag (e.g. ruby) will all be listed under the same tags, and each could specify a different thing needing docs. It takes all of a minute to start a new project.

I may sound like an old grump, but Ruby developers really ought to learn how to write adequate documentation via RDoc and patch it against the project source (and the core developers of the Ruby projects need to be receptive to documentation patches). Attaching the documentation to the source makes it authoritative—the mish-mash of semi-accurate blog posts that end up being the defacto Rails documentation are pretty shameful.

Having a bevy of site-owners competing for traffic as authoritative documentation sites does no one (other than the folks who run those sites) any good. The community is built as a user base around code and is going to be best served if the documentation is applied where it belongs.

PS – Ignoring the GNU Info rift, Unix man pages are a great example of free, community-driven, open source documentation…

Hi. I agree with you completely! This post couldn’t come at a better time, as I am currently, and for the rest of this week, once again able to work on railshelp.com!

I think you provide a really good insight on something I had not paid enough attention to before, and I’m exited to integrate this into the new version of the site!

Thanks!

I’d guess that at least part of the problem is that it’s more interesting to build a Rails documentation site than it is to write/update Rails documentation, no matter how much more valuable it would be to do the latter. And I sympathise with that.

It’s also true that producing & maintaining quality documentation is not simple and can be time-consuming, particularly if it has to be done after the fact and by party or parties not the original author(s).

So I’d agree that we need a model that offers incentives of some sort to people prepared to spend their own time engaged in a task that is not their first choice of activity.

Well said. Everyone seems to have a quirky titled rails doc/plugin/blog aggregator site on the back burner (including most of the people who have commented thus far) but no viable business model for making it work. Clout in the community and a well designed yet empty site (even with complementary lighthouse bug tracking, complementary hosting by engine yard, peep code ads on the side (no offense) and an interface ever so slightly different than 37signals) is not going to be valuable to the community.

Nathan: You’re right that most people don’t have a business model, in which case it comes down to personal dedication or sheer interest in the topic. Ruby Inside has no business model (although it makes an income) yet the quantity or quality of posts has been consistent since launch. I don’t see why someone isn’t able to run a documentation site in the same way. It just takes commitment, but unfortunately some people tend to fall at the first hurdle with any project. That’s a trait common all over, not just in documentation projects (I’ve seen many great Ruby blogs come and go in the same way).

I think you’re on to something there Geoff. What motivates me to keep Railscasts going? I enjoy teaching, but I wouldn’t do it anonymously for another site. That’s what most of the documentation sites out there are asking us to do.

What I like is something I can call my own. Getting feedback from viewers and knowing that people are learning from my teaching makes it all worthwhile. Most of that is lost when going through a third party.

That’s an excellent suggestion. Even for open source projects with superb documentation (like Rails), it rarely extends past simple explanation of the API. All the good stuff is in blogs, and especially design-related lessons.

There’s an important distinction that underlies some of differences of perspective expressed here—that between documentation and tutorial. Rails needs a single, authoritative documentation set, and while there could be multiple presentations of it, it really should be one set. api.rubyonrails.org should be the single authoritative place, but it’s presentation is so weak and lacking in features that it has spurred multiple other presentations.

I think the community would be best served by a single authoritative documentation site, with a good interface and the ability for people to add comments—something that both PHP and MySQL have, for example.

Tutorials are an entirely different beast. Very experienced developers may need nothing but the documentation and the source code, but most people need more explanation and examples than the documentation will ever provide. That’s the role that blogs fill, and in which we hope to make a contribution with BuildingWebApps.com.

Ryan Bates is definitely spot on there, I’ve noticed that when there’s a chart of the top 10 documentation patchers (or top 10 anything) the competition aspect of it goes berserk. For instance Code Golf Challenges shows the top 10 golfers and the competition is intense between them.

I understand the difficulties of course. We would have to find out who did the original patches or just start from 0 which would be annoying. But I think engaging our competitive narcissistic side is probably the best way to go about it.

@Chuck, competition is nice, but isn’t what currently motivates me. What does is knowing that people are getting something valuable out of the effort I put into it.

With collaborative documentation projects I feel like I’m speaking to a wall. Maybe there’s someone listening on the other side, but I don’t really know. Even if there are people listening, they can’t tell who I am. I just like to see the fruits of my labor and get some credit for it.

Perhaps the answer to Ryan Bates’ (and others I’m sure) anonymity issue is aggregation. Pull the best content from all the best Ruby/Rails blogs and tie them together in a cohesive way while maintaining attribution. Maybe even allow others to edit said posts as times and practices change.

Ad revenue would be shared with authors proportionally to pageviews (i.e., 10% of the hits are for errtheblog articles, pay them 10% of the revenue). Points could be awarded similar to Working With Rails that would allow revenue sharing proportional to activity.

If it was official enough it might tease more folks to get into blogging about Rails on their own sites as well.

In terms of the Rails API docs, they work well as a reference and are always up to date. It’s great if you forget which order arguments go for a particular function but it’s not very accessible for the first timer or helpful for those looking for best practices.

Agreed Geoffrey. There are quite a few sites coming out of the woodwork to help the documentation issues. One thing is I do agree with Ryan for the most part and doing some kind of aggregation of blogs would be great. Though I wonder how PHP and Django can make their API + Comments work so well, but we can’t? Maybe it will take a project backed by the Rails core team, pre-filled with API docs, open comments, and possibly blog links? I’d love to venture a project that way instead of 12 separate spinoffs of the same type of site.

Personally, what I’d like to see are more cookbook-style examples. I can code Perl all day long with only one reference: the google cache of the o’reilly perl cookbook online.

Speaking of Perl documentation, http://www.perlmonks.org has a pretty interesting format, with moderated question-and-answer forums where high quality questions first get answered by proficient coders, and then posted at the ‘Monastery Gates’ for the public to read and comment further on. They also have a useful code archive.

According to the clay shirky et al , social software works best when you have actions that benefit individuals selfishly, which also have unintended benefits. Costs for doing good things have to be low. You’ll know it’s working when it is worth being spammed.

Rails may actually be in a sweetspot right now. Full of passionate folks, but not yet valuable enough for total spamming.

You might be able to have a parallel effort: More strictness on plugin or gem acceptance being accompanied by docs, or by letting documenters compete by getting linkbacks.

But the best bit may just be a sight where you could trackback from your post to the methods or objects you are talking about. You make info, you have a link on the site. Then you let people bubble up good info with a buttons for “this is good info”, “this is erroneous”, “this is spam.” You might also be able to construct this just using the technorati data…

That way, the barrier to entry is low, it benefits the authors, and you have a way to combat spam.

I agree with Ryan. However, I think if Rails created a better doc project (php/mysql style) people would be willing to contribute semi-anonymously based on the fact that they know they are contributing to the “official” documentation. Why would I invest an incredible amount of time documenting for XYZ.com when I have no assurance if they will be around in a year, or even a month from now? Will my contribution be valued (read by enough people to justify my time)?

Evidence is that the rails wiki has a fairly large amount of activity, however, it is my opinion that a wiki is just not the best format for documentation purposes. No uniform organization or formatting can be expected and it makes it a pain to use and update (which is why so much of the wiki is now out of date).

I think contributors and commenters could have a Gravatar or similar to reduce the anonymity and provide traffic to the blogs of those who post good content. External blog posts could be incorporated as an article specific blogroll where links are ranked by a Diggish metric. But the key thing is, it has to be *.rubyonrails.com.

I agree with chad that this needs to be a *.rubyonrails.com effort. One solution to the anonymity problem might be segment the docs into different segments with each segment having an ‘owner’. That person would be taking on the responsibility of flushing out the docs in that section. Another interesting aspect would be adding an ‘external resources’ layer to the standard docs. So say I’m looking at the docs for ActionController::Caching::Pages, I could see a list of blog posts that people have linked up to that section on the docs.

There are two sides to that. The first one is Hieraki. Hieraki on Rails site was gorgeous. It did what it should, it helped writing a book about rails, and I used it to actually learn Rails long before AWDWR became abailable.

After that, Hieraki went into disrepair and languished. Among others because selling a book is a clear commercial message, and a competing open online resource wouldn’t do much good to the sales. That’s the flipside of the coin BTW.

If you want the problem of documentation to be solved quickly – promote the hireaki instead of the wiki and rdoc. Rdoc (commented method reference) can come into play much later, and is doable (provided you actually comment on public APIs and not on the things which are always in flux).

There are two sides to that. The first one is Hieraki. Hieraki on Rails site was gorgeous. It did what it should, it helped writing a book about rails, and I used it to actually learn Rails long before AWDWR became abailable.

After that, Hieraki went into disrepair and languished. Among others because selling a book is a clear commercial message, and a competing open online resource wouldn’t do much good to the sales. That’s the flipside of the coin BTW.

If you want the problem of documentation to be solved quickly – promote the hireaki instead of the wiki and rdoc. Rdoc (commented method reference) can come into play much later, and is doable (provided you actually comment on public APIs and not on the things which are always in flux).

I just want to add one thing: An issue (brought to the table at this nights doc/writers BoF at the RCE) that is easy to be ignored is the language issue. The PHP documentation team actually manages to translate the docs to a wide range of languages and this really helps some people. Probably not us early adopters (I actually prefer reading english to reading bad german translations) but there’s a lot of people out there that we completely loose because of the languange barrier. This also shows one particularily bad limitiation of the RDoc system (which is essentially the same for JavaDocs or anything else generated from source): No way to translate it without leaving the easy path of generation.

I really like the blog post aggregator stuff and we actually came back to that idea on the BoF, so it’s kinda imminent, I guess. I tried to sum up some of our thoughts of tonight (probably a bit filtered by my own thoughts) at my blog .

The most important thing at the moment is, I guess: We need a joined effort on glueing all ends together so that, in the end, we have an officially supported, working system for collaboration on the docs, translating the docs, searching the docs and so forth.

We’ll see how much we can stirr that up on the railsconf tomorrow. :)

My team has been slowly working on a project that shares some ideas with what Geoffrey is talking about here. We’re still in the sketchy/planning phases- but we’ve got some ideas for keeping the content evolving without a massive effort on the part of editors to scour the ‘net for relevant resources. That’s one of the key things we see as crucial to making anything like this a success.

We even used a quote from this blog as an example comment in the mock.

No motivation? What’s my motivation to write free code?

(Answer: to scratch an itch. If it was easy to fix documentation, I’d help with that, too. Usually it isn’t.)

I’m just getting to the point in my Rails experience where I’m seriously picking through the Rails source code to learn how the framework works, to determine best practices for code style, and to look for ways to extend the framework in ways I need.

I’d love to contribute to the documentation of the Rails source directly as I go through that process. http://api.rubyonrails.org should be the de facto documentation and to get my doc patches accepted would be a great personal achievement.

What would make the achievement just a little more worthwhile is if it is measured and evaluated. http://api.rubyonrails.org could have Digg-style thumbs-up, thumbs-down buttons next to each doc section. Those ratings would give the community feedback about which areas of the docs currently need the most love. They would also be compared against the authors of those docs so that I know whether people find my work valuable to them.

A simple “leaderboard” list of most-valued documenters would be great motivation for myself and others. I’m sure a consortium of successful Rails consultancies such as thoughtbot, Planet Argon, Elevated Rails, etc. would be willing to chip in to reward those top documenters on a monthly basis.

Back when this thread first started, I mentioned that I was building a site that would address some of these needs. It’s still a work in progress, but we’ve opened it up to public access, so please check it out and let me know what you think! BuildingWebApps.com

We have just a few articles that we’ve written, with many more to come. We have tagged and rated about 500 other web resources, including blog articles and other things. This will grow dramatically in the coming weeks.