Present Perfect

It's Friday night, the missus is away from home, and I have the place to myself after work. Most people would spend it either out or on the couch. I went for option two, with a twist - dust off that CouchDB book again and see if we can get it to work this time.

I last tried this a bunch of weeks ago, and couldn't really get a magic mix working of that day's version of the book (it's a work in progress), CouchDB's trunk (it didn't yet have user authentication I think), and Sofa's git master (there's only one branch, master, and it already implemented user authentication from the 0.11 branch). It was a frustrating experience for a newcomer, since when things go wrong because of a version mismatch you end up with obtuse or confusing error messages. The #couchdb IRC channel on freenode was helpful but couldn't offer much more than an apology that the book was in a state of flux.

Today I definitely had more luck. I was able to clone the sofa app, which is a blog example, make a post, and see some JSON action.

Now I understand most of the concepts, but I don't know how to get started. The book explains how to get the sample sofa application and run it, and even customise it, but I don't know how you're supposed to start from scratch.

Again, IRC helped out: there is a 'couchapp generate' command that sets you off with a default structure. After that, I copied the shows/edit.js and templates/edit.html from the sofa example because I thought I'd start out by providing an edit page for my test application.

I was then greeted with an obtuse error message, that included something like this:

[error] [<0.6600.0>] OS Process Error :: {compilation_error,
< <"expression does not eval to a function.

and then a bunch of javascript code expanded from edit.js

I was guessing this was a syntax error somewhere, so I started removing code until I figured out path.js was the culprit. I haven't actually written javascript before outside of a web app, so I wanted to verify by syntax checking the javascript files. Apparently these days you can just install a javascript binary on your system, and sure enough, running that on path.js gave me:

(sandbox)[thomas@ana gtd]$ js vendor/couchapp/path.js
vendor/couchapp/path.js:8: SyntaxError: syntax error:
vendor/couchapp/path.js:8: if (!noJson) && (name == "key" || name == "startkey" || name == "endkey") {
vendor/couchapp/path.js:8: ...................^

While I am no javascript expert, I just randomly guessed I needed additional parenthesises around the if argument, and lo and behold, that fixed my problem.

I went around browsing through couchapp's github pages to see if the code still has that issue, and found this fix (interspersed with unrelated fixes, boo).

A quick check later on IRC told me that there is in fact a newer release than the couchapp I was using (0.3.31 vs. 0.3.32) that somehow easy_install did not pick up on - with a little luck you won't run into the same problem as me.

Anyway, why go through all this detail ? Because it reminds me of an opinion of mine about the five minute run experience of a project. I truly believe that most people evaluate a project within the first five minutes of trying it. People will invest a little bit of their time in your project, increasing the time they spend at each step if the previous step gave them a good feeling and/or a rewarding experience. It usually starts by reading the elevator pitch of your project somewhere. That's a five second read. If that piques their interest, they might follow through on a blog post or go to your website. Another quick step.

If that looks promising, they may read your about page, your FAQ, skim through your introductory chapter if it's short enough, or go look at your screenshots. Maybe a minute ? And if they're still with you, they may try to download and install the software so they can actually run it.

If that is easy (and that means, it's just one click or command - the .exe or an installation instruction for a distro package) you've gotten them to the point where they can actually run the software. If it's harder (a bunch of commands, building from source, dependency hunting, ...) you're likely to loose them. Imagine it's easy and takes a few minutes waiting to download.

Now the clock really starts. Your app has five minutes to convince the user that it actually seems like it's working, has some level of quality, and might do something interesting the user cares about. If the user can do something useful within those five minutes, you've won him over. But if within those five minutes he manages to make the program throw up errors, do something wrong, or just plain crash, or if he can't do anything useful in it, he's likely to discard it completely and go on to the next app he wants to try.

This counts doubly when someone actually needs to do something specific and is just looking for different applications to do the task. If you find ten twitter clients on Freshmeat, how do you decide which one you'll want to use ?

Of course, there are exceptions. So far CouchDB's five minute run experience hasn't been so good compared to everything before it. The elevator pitch is right up my alley, this thing does something I'm interested in exploring. The website ticks all the right boxes, the description is excellent, and that couchdb book looks good.

But then actually trying it quickly became a swamp. Fedora only had 0.9.1 - not CouchDB's fault of course, but the book is written for 0.10 which wasn't released yet. Worse, the book was out of sync with the versions it recommended I use to try it. I didn't make time to look at CouchDB for a few weeks. That was a lucky shot - this time around that part was much better, and I invested an hour in playing with Sofa.

The second roadblock was this couchapp problem. A really minor code bug, but again took me a while to figure out what was going on, not helped by the confusing error message.

Why am I breaking my own five minute run rule here ? Because I want to see if CouchDB lives up to the promise - if it really can do all this replication stuff, it seems like a perfect match for a few of my projects. I'm believing the opinion of a few people I trust. But normally, I would have moved on to playing with one of the other key-value stores instead and give them an equal chance for my developer dollar.

In any case, I'm going to push ahead some more now that I found the bug. Hopefully I have a simple edit and view working sometime this weekend if I find some more time.

Sleepy time!

It's Friday night, the missus is away from home, and I have the place to myself after work. Most people would spend it either out or on the couch. I...