December 4, 2010

How to Make it Easy for New Developers to Adopt Your Open Source Project

James Gregory is one of my heroes in the .NET community – he’s the creator of Fluent NHibernate, my favorite new ORM (Object-Relational Mapper) for my ASP.NET MVC projects. James expressed some dismay earlier today when a newbie Fluent NHibernate developer posted a $100+ bounty for a few basic usage examples; having just recently taught myself the very things the developer was asking for, I can empathize.

NHibernate (Fluent NHibernate runs on top of it) is a bear of an open source project for new developers – it’s a mature project that solves a problem with a massive surface area and the NHibernate community is comprised of experienced developers who’ve been using it for years. It can be difficult for new developers to get involved, as the learning curve is steep even for just adopting the project, let alone contributing to it.

So how can we make it easier for new developers to adopt advanced, mature projects like NHibernate?

Here are some ideas:

  1. Offer new developers a low-friction adoption path – in many of the projects I’ve tried to adopt over the years, I’ve had a difficult time figuring out what the best way to start using some of them itself. The thing that is going to kill adoption of your project is friction – if a new developer encounters resistance just trying to build a basic “Hello World” equivalent on top of your project, they’re going to lose interest and try to find something else. Gently guide your developers down on low-friction path to adoption.

  2. Describing the functionality of features isn’t enough; explain their intent – NHibernate has a ton of content for in its Wiki for new developers, but few of them explain the intent behind NHibernate’s powerful features – what new developers really need to understand is why and when they should use certain facets of your project’s functionality, not so much how that functionality works.

  3. Use real-world examples in the documentation – one issue that frustrates me when I’m trying to learn a new technology is when all of the 101-level examples are canned. I don’t want a Fibonacci sequence example or anything else that I would never use in the real-world. Show me the hard stuff; show me how to build a human user-interaction around your project’s technology; show me how to use it in a middle use-case; and show me how to integrate your technology into projects that resemble production scenarios.

  4. Include reference materials – .NET developers get to use object explorer as an option of last resort for reference materials, which is a plus. However, the goal of open source project leads should be to make it easy for new adopters to find the right piece of functionality to suit their needs, and a reference guide is often the best way to do it.

  5. StackOverFlow first – I was trying to troubleshoot a small Fluent NHibernate issue I ran into earlier today (will blog about it soon), and I saw a number of questions identical to my own on StackOverFlow – all of them unanswered. The first place your users are going to turn when they run into trouble is Bing and Google, and StackOverFlow will dominate the results; answering someone’s question on StackOverFlow doesn’t solve a problem for just the person who asked it – it answers the question for many other people who may run into the same issues down the road.

Open source is fun, and it's fun for new developers too. Onboarding new developers to your project isn't as sexy as writing a patch or coming out with a new version, but it's ultimately better for the longevity of the community.

If there's anything else I should add to this list, please add them in the comments!

Discussion, links, and tweets

I'm the CTO and founder of Petabridge, where I'm making distributed programming for .NET developers easy by working on Akka.NET, Phobos, and more..