Tuesday, 22 July 2008

More thoughts on Rails-doc 2.0

I'd been re-contemplating the Rails-doc 2.0 site and had begun to write a post about the minor annoyances I found, when suddenly up popped a new post by Jeremy on rubycorner.

I guess I'm not the only person whose experience was akin to: "OMG wow! *click* *click* hang on..."

My annoyances from rails-doc 2.0

There's not a lot wrong with rails-doc 2.0, the following are merely annoying.

Click depth

One of the benefits of the previous rails-doc site is that it's all there at your fingertips all the time. Rails has a deep hierarchy and now the only way into it is to search randomly. This can be fun - the auto-prompter is pretty good... as long as you know exactly what you're looking for. But on the old site, if you can't quite recall what you're looking for, you can browse down to the list alphabetically until you find it. With the new site you have to delete your old search and continue to try other names. Search helps, but having a browse-alternative is also helpful.

Another problem with deep click-hierarchies is that you can't get as much information at once. On the original site, all the methods are on the same page - and all you need do is click the anchor or scroll down to them to get a feel for the whole class. You don't have to keep clicking through and back if you want to look at each of the methods.

Searching code

...requires code-sensitive search. If I type "default_error_messages" it means something entirely different to a search with the words "default error messages" somewhere in the body.

version consistency

If I chose version 1.2.6 for the ActiveRecord class, chances are pretty strong that I'll want to keep looking at version 1.2.6 when I click through to the methods... or anywhere else, for that matter. I think there's a strong case for persisting the chosen version.

Is there really a problem?

As you might notice, these are just GUI annoyances not real issues, as such. So is there really a problem?

Jeremy points out that user-added notes are all well and good, but what we need is for the actual real rails-doc to be updated. That isn't going to happen here (at least with the current incarnation). His proposed solution sounds great - and I'll look forward to its release. Perhaps he should team up with the rails-doc.org folks ;)

But has it got anything right?

Jeremy actually stated this succinctly:

"If I’d known that all we needed was a good looking RDoc app, I could’ve fixed the problem a while ago."

Lets face it, we're geeks and we love shiny new toys... Rails being the epitomy of the shiny new thing. So yes, rails-doc 2.0 got one thing absolutely right - it provides a pretty interface that is easy and fun to explore. That's often all it takes folks like us to start contributing - so they got that right.


Otto Hilska said...

Greetings from the rails-doc.org team. :) We hope to receive an e-mail if you have some improvement ideas like these. We're constantly working on the site, but we can't take it to the right direction if the feedback is hidden around the Internet.

Some answers anyway:

1) We do have the Browse feature. It only shows modules, but I feel that it's easier to find stuff when the methods are not cluttering the view.

2) The full-text search requires lots of tuning. We're interested about cases where you didn't find what you expected.

3) Usually the case is that the latest version has the best documentation. Sometimes there're parameter incompatibilities between versions, and that's why we provide you the access to the older versions.

If we wanted to do a wiki-like editing for the documentation, we of course could. I'm going to blog in a couple of days about how I disagree with Jeremy.

Taryn said...

Hi team. Yeah, I was planning to send my list in, but hadn't got that far ;)
I know you have better things to do than hunt around the internet for people's feedback - though I do appreciate you taking the time do so here. :)

All-in-all I think the site is pretty good, and it's great that there's so much buzz about it as we all seem to be agreed that there needs to be more documentation done!

Thanks for the feedback on my own personal annoyances. :)

I'll have a think about your answers and a bit more of a play on the site and then send you feedback on anything I still can't get working.

I'll look forward to your response to Jeremy!