Your open source product is great, I think

I’m consistently awed by how poorly most open-source teams present their technology to their core audience of fellow programmers.

There are so many great examples of freely-available technology out there that fail to get widely adopted due to their abysmal out-of-the-box experience. The saddest part is that most of these hidden gems just need a tiny bit of thought around their documentation, presentation and packaging to really get the downloads kicking in.

As an example, I recently started to evaluate REST toolkits for Java and stumbled upon Restlet. It seemed like it could do all that I needed, but going beyond the level of “Hello, World!” took far more effort than I had hoped. There was documentation — oh boy, was there ever documentation — but it was spread all over the place: their own website, the online Javadoc, forum posts with snippets of code from the authors, sample chapters of their upcoming book online, the code within the distribution, and so on. But there wasn’t a single place from where I could download and run a reasonably well-featured demo that showed me how to build something of perceptible value.

I almost gave up on Restlet entirely. I decided to stick with it because there was obviously a large and enthusiastic community of other programmers out there who were already happy with it, so I kept up my search for more helpful information. After much fruitless browsing on Restlet’s own documentation site, Google led me to a 2-year old blog post by someone completely unaffiliated with the project which contained a decent sample application. And it wasn’t like this filled the final gap in my research either: had I found it at the beginning when I had first landed on Restlet’s own site, I would have never even strayed into their documentation jungle. I simply wouldn’t have needed to.

Now Restlet is actually quite a well-designed library (and here comes the kicker) once you learn it. That is a caveat which software engineers should hope never to see used in the same sentence as their product’s name.

I’ve seen too many promising projects suffer because of this unfortunate – and completely avoidable – issue. Open-source programmers have got to stop thinking that their audience is happy to get stuck into the source code of their libraries for a solid week before becoming productive. We’re busy people with jobs that require us to solve problems today, so if your website and product don’t help me get things done quickly, I’m leaving. Forever.

Thankfully, it’s not that much work to get it right! Just remember that your first communications with new audiences may last only a couple of minutes, so get your most important messages across to us quickly. Secondly, give us a clear path to proceed and learn once we’ve taken the bait.

In other words, show us what you’ve got, and show us fast.

You could always run a focus group to examine how first-time users interact with your product, but there’s no need. We all do it basically the same way, and I’m going to write it up for you. Here’s what I do when I have to quickly find and evaluate a potential open-source product:

1. Google the problem domain. I’m unlikely to go beyond the first page of results.
2. Click around to find a product that looks relevant and seems at least somewhat mature. Your FAQ is as far as most will go at this point, so it had better be well-organized and primarily address the questions that newbies like myself will typically have.
3. Download and install. If you require registration from me then it’s game over. If I don’t see a link called Download displayed clearly on your project page I’m very unlikely to spend time searching for it. Oh, and please build a package for the most popular operating systems out there. In fact, if you can make this step a complete no-brainer by using a de-facto standard repository (maven or apt come to mind) then I’m going to be very happy indeed.
4. Find a sample inside it that looks relevant to the problem at hand. Running a sample successfully first-time will make me feel all smart and brainy, so just make them work magically without requiring me to edit any files or fiddle with any flux capacitors.
5. Fun playtime is next as I drill into the sample’s code and see if it can be tweaked to solve the real problem which led me to your gizmo in the first place.
6. If I have trouble with my playtime tweaking, I may look at your online documentation. However the less time I spend in there and the more time I spend successfully using real features, the better.

So remember: patience is a virtue, but programmers are really, really busy.