Papa's Perspective

Git Involved in Open Source

Developers are contributing to more than a million projects on GitHub -- why aren't you?

• By John Papa
• 08/01/2012

Many developers are not only great problem solvers, they also excel at sharing code. Their roles often lead them on journeys where they have to fill a gap, create a widget or simply build a better mousetrap. It's part of the continual evolution of our industry. And lately, developers are sharing more libraries and code than ever.

Several factors have contributed to the sharing trend. Foremost is the innate desire in many developers to spread the good news when they've solved a problem.

The popularity of sites like github.com and the trend toward cross-platform applications are also driving developers to create more open source software. GitHub is making it simple to store and share coding ideas -- and, more importantly, allowing other developers to fork code and contribute back to open source libraries. Microsoft has gotten into the act with increased support for GitHub and especially NuGet, its open source package manager. You can now download open source packages directly from Visual Studio using NuGet.

Nothing Is Too Small
You don't have to have a major breakthrough to create open source software, nor do you need a brand-new or unique idea. Sometimes it's good to share a better way to solve a problem or an alternative option. Recently, my friend Hans Fjällemark and I developed a jQuery plug-in that creates custom alert messages. We didn't like the choices we found and wanted something dead simple to use that could easily be extended or customized. The entire code base is 159 lines of code, and it's completely reusable. Once we were done, we decided to clean it up and share it on GitHub and NuGet. And thus toastr was born.

I mention toastr because it's about as small a library as you can get, and it's relatable. The key is that no idea is too small. If you have something useful, odds are that other developers will find it useful too.

Keep It Simple
One problem with many libraries is complex APIs. Sometimes complex APIs exist because the developer felt that the library needed to solve too many problems. My original idea for toastr had 10 methods you could call to pop up a toast message, all with several overloads. I won't go into the crazy ideas I had, but once I took a step back and realized all it needed was a set of four methods for the types of toast (info, warning, error and success) and each method could support a simple API with many defaults, it became much more useful and easier to understand.

One of the keys to sharing code and having your code adopted is making it easy to use. It doesn't get much easier than toastr.success(‘Your data was saved!'). There's little to no learning curve for this API. Of course, you also want to allow customization, but the key is simplicity.

Explain It
Another downfall of some open source libraries is that their landing page doesn't do a good job of quickly explaining what the library does, or how to use it. Don't fall into that trap. GitHub has a readme.md file that makes it simple to add this information on the landing page, and the first thing I like to see when I find a library is a one- or two-line description of the library. What the heck is it, and when would I want to use it? Fjällemark and I explain on our landing page that toastr is a JavaScript library for Gnome/Growl-type non-blocking notifications.

Next, show me the immediate steps to use it. Toastr has three steps to help you get started. First, link to the toastr.css, then link to the toastr.js and then write toastr.info(‘Hello world'). Developers are flooded with new libraries all the time, so by making it take just a minute to get going they're more likely to try it.

Finally, show me a demo. Make it even easier for developers to adopt your library. Sometimes, developers won't read any instructions. By providing this option too, you increase the chances of having your library adopted. You can check out the toastr demo and try out toastr in all its glory on GitHub.

Just Do It
Get your code up on GitHub. Don't wait for it to be perfect, either -- that may never happen. Once your code runs, publish it and let others check it out. You can always push updates, and the best part is you may get feedback and contributions from the community. So take the code that you've been building and polishing, and push it today!