The state of the documentation

Posted by Tom on 2008-04-12

While chatting in the hobo IRC channel yesterday, I realised that I should probably do a blog post on the state of the documentation. We’re far from done here. I don’t want anyone to get the false impression that you’re expected to figure out how to use Hobo from the tutorials and guides that we’ve posted already.

If you wanted to use Hobo not so long ago, pretty much your only option was reading the source and asking questions. If you want to use Hobo now, you’ve got some reasonable docs to get you going, but you’ll still need to read some source (especially the DRYML libraries in vendor/plugins/hobo/taglibs). Eventually, you’ll be able to get by on the docs alone and everyone will be happy :-)

There’s all sorts of details that we haven’t documented at all, but there’s two really big gaps: customising your controllers and the Rapid tag library. What I really wanted to talk about in this post is Rapid.

Rapid, in my opinion, is the best part of Hobo. You could say (and in fact I think I did somewhere or other) that everything else in Hobo exists to make Rapid possible. The combination of development speed and flexibility that Rapid brings is something I can’t say I’ve seen anywhere else.

But there’s a catch. You have to know it. And there’s a lot to know: layers and layers of tags calling tags calling tags. If you know your way around it from top to bottom, you’re singing. If you don’t, you’re probably writing way more view code than you need to.

You should get a good sense of this from the Agility tutorial. Towards the end you’re asked to code up bits and pieces of DRYML. These snippets seem to add functionality that far outweighs their size, but you must be thinking “how was I supposed to know that?!”

Some folk seem perfectly happy to read the DRYML taglibs and find their way around that way, but we really, really need docs for this stuff.

This is not meant as an apology, and it’s not going to be a promise to deliver X by Y. It’s just to let you know that those docs are very much on the to do list (and near the top), and please don’t think that you’re expected to just know what to do.

An idea that came out of that IRC chat was to create a tutorial that starts with a full app, in “normal Rails” style, and goes through how to gradually Hoboize it. In the view layer we could explain how to factor out all the HTML into layers of DRYML tags. That would not only show how to use bits and pieces from Rapid, but would also illustrate why Rapid is like it is. It would throw a lot of light on the whole of Hobo in fact. Could be a lot of work though, so don’t hold your breath until it’s ready :-)

p.s. On the subject of docs I just noticed that the HoboSupport docs are messed up – there’s a whole bunch of pages that aren’t linked to. like this one for example. Will fix!



(edit)