The five minute rule

It seems sometimes people just completely miss the point, even the brightest of them. Yesterday I was doing some prototyping for some new project I am working on which is based on JBoss EJB3 implementation, and since most of my background comes from Spring based project, I was looking for some answers. Nothing too complicated, mind you, I just needed some way to have one of the EJB beans to hold some shared state for all the application, something that is really straightforward in Spring, and something that I assume most of the applications out there today need at one point or another.

So, since I am no JBoss expert (yet :)) I did the sensible thing and tried to google it. Well, simple queries didn’t find anything for me (“jboss service”, “jboss singleton”, “jboss ejb singleton” etc), but in the end I stumbled upon something called @Service annotation which is a proprietary annotation of JBoss and can be used for this kind of stuff. Which is documented in this page. Which is while it is couple of pages long and have some code examples lacks one very basic thing – it doesn’t show how to use the thing in the simplest and most common use case, the one I was actually looking for. So instead of just copying and pasting the sample into my code and just running it and continuing to some other stuff I had to spend about an hour trying to figure this stuff out. (BTW the solution turned out extremely simple, elegant and it doesn’t require any of the stuff that is printed on that “help” page – I will put it in a separate post for others to reuse)

Which is why I think some people just don’t get it. I mean they are great developers and the eventual solution is really great and working flawlessly – but they miss the most  important point. Open source frameworks and projects that provide infrastructure are just tools that allow us developers to solve some common problems. The reason these things are actually used (and not reimplemented in house) is that they provide solutions without the need to really go deep and understand all the implementation issues. When I write some application for an end user any time spent on figuring out some stuff that should have been in the manual is time not spent on providing value to my customer.

And this is my main point – you must know who your customer is. It just doesn’t work otherwise. And if you develop open source project that is going to be used by other developers – your customers are  those other developers, usually the ones working on end user oriented software.  This is not about who got the coolest implementation or the tightest algorithm or the most generic platform. This is about providing simple solutions to most common problems. And the reason why you should care is that even though we are not the ones paying your bills  – your success and success of your project is directly proportional to its adoption rate. And guess where that adoption rate comes from.

Here is an example of project that does get it – Terracotta. It will take you less than 5 minutes to understand what it does and what problems it solves. And if you decide to try it out, it will take you less than 5 mintues to download and run an interactive sample of the technology (which is very cool by the way). Compare that site with site for JBoss Microcontainer which is the core of the new JBoss 5 release. I assume it is really good piece of technology but try to spend only 5 minutes on their site and try to understand what it does and whether is solves any of your problems. I couldn’t. And if I was really evaluating it I would just discard it at that point and go look at the next thing. Because there is always another thing (competition is great isn’t it?).

So here is my 5 minute rule – make sure your site and documentation can provide some initial idea of what problems you solve in less than 5 minutes. Make sure that for the most common problems the solution (including examples or better yet cookbook style recipe) is no father than 5 minutes away. Otherwise you are just not competitive with the projects (which by the way may be less technologically advanced) that do provide those answers. Take a look at the success of Spring Framework. Take a look at the success of Ruby on Rails when they took the world by storm using that video of creating a blog application in under 15 minutes. They did it despite the many technological problems that they had (like native threads and performance). This is really fast world. Help yourself by helping me quickly. Otherwise no one will care.