Save time managing and deploying your node.js app. Code faster with jitsu and npm

Understanding Open Source Branding

About the author

nodejitsu nodejitsu

What is product? At Nodejitsu our definition is simple: product is what our users are consuming every day. It doesn't matter if it is our Platform-as-a-Service,, or if it is one of our many open source libraries. This definition is why from very early on at Nodejitsu we decided to treat our open source libraries with the same level of attention and care that we do our public Platform-as-a-Service.

Successful open source libraries and initiatives require the same kind of attention to branding that many think is reserved for profit focused products. In other words, Open Source Doesn't Just Market Itself. Lets explore how discoverability, time to start (i.e. how long it takes to use what you've built), community, and some good old fashioned hustling can help build Open Source brands.


tl;dr? This is the place for you:

"Don't Make Me Think"

A clear concise explanation of your Open Source offering is the best way to get users interested in what you're developing. Zach Holman from Github put it eloquently in his article Open Source Doesn't Just Market Itsef:

My favorite marketing of all time is documentation. We all loathe sleazy marketing, and by definition I like to think documentation can't be sleazy because it solves a real purpose: teaching everyone about the project.

Take a step back and think about discoverability and time to start from a user's point of view: they somehow stumbled upon your project. They probably don't know you or how awesome you are. They are looking for a solution to a problem that your project may or may not solve. The quicker you help them make this decision the better.

Documentation comes in all flavors, each of which serves a different purpose. Every type of documentation increases the momentum and reduces the perceived risk of your project so the more the better. Just like a startup, building momentum is a key metric to success: "Build enough momentum and they will come."

  • README: This is Open Source MVP. Without a README (preferrably Markdown on Github), at least half the users that discover your project will simply move on. If you have a lot of Open Source projects be consistent. Use an outline; we do at Nodejitsu.
  • Examples: If your library has several use cases, then it is absolutely critical to include example code and briefly discuss it in your README.
  • Project Website: Even better. A custom project website allows you to create a true brand for your project; a logo, a catchy tag-line, whatever. Be sure to link back to Github or elsewhere.
  • Blog Posts and Tutorials: This is the long tail of Open Source branding. Each blog post or descriptive tutorial you write will gather more momentum and lower the perceived risk of your Open Source offering.

Beyond documentation remember that this is Open Source: people will read your code. If you haven't finished part of your API or there is work left to be done be clear about it and expect feedback. Or, if you've decided on a particular way to write your code (such as promises or a particular coding style), realize many users will be immediately dismissive. This is particularly important in Javascript:

If your code uses a compiled fibers library, or something that transforms the code, then it's much harder for me to figure out what the heck is going on. The introspection is gone.

Divorce Your Ego

To me, the emotional investment in creating Open Source is best summed up by Isaac Schlueter:

It's like having children. Seems like a lot of pointless busy-work, and then you do it, probably without meaning or wanting to, and then suddenly fall so in love, you can't understand why everyone doesn't go as nuts over this little food-to-poop converter as you do. If you're not careful, you'll end up writing 3 or 4 more.

Divorcing yourself from your ego and these emotions is hard. You have probably put in countless hours of your own time just because you thought it was cool. But it is crucial to Open Source success: your users probably don't want your life story about why you created your library, or how it is going to solve a problem they don't have.

They also don't want to get an attitude when they open up an issue or reach out to you over Twitter, Email, or your Mailing list. A user may not completely understand the problem you're solving or is just plain misusing your API. An open-minded and understanding attitude is your greatest ally. This doesn't mean you have to divorce yourself from your opinions, just stay objective and never make it personal.

Build a Community

Beyond having a simple and concise explanation of what your Open Source offering is it is important to create a place where questions and FAQs can be easily found and responded to. Think of this as "beyond documentation."

When working with these community building resources it is crucial to realize your first interaction with a user may be your last. And, if you provide a great experience for your Open Source users they will become your community's greatest asset: responding to Github issues, helping new users, writing Open Source which expands on your own, authoring a critical mass of blog posts, and more. At Nodejitsu most of our new hires come out of this group of users who respond to common GitHub issues and mailing list threads.

So bury your ego and be as friendly as you can. That's not to say you have to do your users' work for them; just set and manage user expectations. We try to respond to every issue within 24 hours; ideally within 5 minutes.

  • GitHub issues: You probably already use GitHub issues for your project. Are you checking them every day? Do you have a FAQ tag for commonly opened issues?
  • Mailing list: Usually a Google group. This is a great place for feature discussions and commonly asked questions. Just look at the nodejs, expressjs, or hookio mailing lists.
  • Twitter: Like it or not, Twitter is a very common place for developers to ask questions. Be prepared for some extra noise in your @ mentions. If you prefer not to use Twitter, be understanding and explain that to users. Also: retweets are one of your best marketing sources.
  • Email: Personally I prefer not to answer questions about Open Source projects over email; I ask that a Github issue be opened. If you're feeling generous, however, it is a great way to build a rapport with one user.

When working with these community resources there are some basic expectations which my co-founder, Marak Squires, outlined in his talk: How to be an Open Source Gangster. The tagline may sound silly, but as the Chief Evangelist at Nodejitsu Marak speaks from experience:

  • Be available: If it takes a user a week to get a response to a pull-request, issue, or email, they probably aren't even a user anymore.
  • Persistence, Tenacity, Follow-through: Stay focused. Every day is a new challenge. Like most developers Open Source is probably your side-project. Be explicit with yourself about how much time you are going to commit. If you go over that limit then find a way to share the workload with a contributor. Just giving up will undo any hard work you've put in.
  • Ignoring Distractions: Don't get distracted by things that don't contribute to your core Open Source offering. "Let the things that don't matter truly slide."
  • Recruitment: Realize that you are not a one man army and engage your contributors vigorously. In the long run, they are the greatest asset to your community.

Open Source at Nodejitsu

Last week at Nodejitsu we announced Flatiron. In addition to the libraries that we announced we took this opportunity to reorganize our personal Github repositories into organizations. We realized that as our Open Source offering grew organizing repositories across multiple Github organizations was the simplest path to high discoverability. This decision is not for everyone, and probably not the correct decision for most individual developers. Just like starting a company, these qualities help your Github organization tell a cohesive story. A good Open Source Github organization does a few things:

  • Cohesive motivation: What problem is your Github organization solving? You don't get a README on your organization page so this should be inferred from the repositories or the homepage URL.
  • Critical mass of repositories: Enough repositories to convince a passive user that the organization is legitimate. This can be extremely difficult if your company is new to Open Source; you may be better off contributing to an existing organization. Releasing several projects at once is a good way to avoid having less than a critical mass.
  • Critical mass of members: Enough users to convince a passive user that the organization is legitimate. is a great way to determine this; it ranks organizations by the sum of the Github followers of all users. This is not a perfect metric by any means, but it can help you determine this.

At Nodejitsu we have decided to delineate our core Open Source offering into several organizations each of which we feel tells a different story:

  • Nodejitsu: Core Open Source libraries from our public Platform-as-a-Service, including jitsu, haibu, and forever.
  • Flatiron: Collection of decoupled Open Source libraries for building tools and web applications in Node.js.
  • A full featured I/O framework for Node.js.
  • Node Apps: A collection of sample applications designed to expedite time-to-start with Node.js on
  • Node Training: Our training materials (when they're finished) along with tutorial-style projects which we use in our training sessions.

Moving and Renaming Personal Repositories

You've probably heard this saying about Computer Science before:

There are only two hard problems in Computer Science: cache invalidation and naming things. -- Phil Karlton

As the quantity of your Open Source libraries increases and they potentially move around to different organizations the first name you picked may no longer be appropriate. Such is the case for the routing component of Flatiron, which today we are renaming from sugarskull to director. We felt that the name director was more in-line with the Flatiron brand.

If you do decide to move personal Open Source repositories to an organization Github will not perform an 301 redirects so the best process is below. It is not ideal by any means, but it is the best Github can do today. If you are concerned about SEO think about this this way: you shouldn't be concerned with the 100 followers you have today; be concerned with the 1,000 followers you want in a year.

  1. Move the repository to your organization from your personal Github

  2. Immediately fork the moved repository back to your personal Github and add a redirection notice.


Hopefully not all of this is new to you; most of it is a distillation of the common wisdom that most developers follow today. A lot of this can be thought of as Open Source in the age of Github.

Prior to GitHub, word about open source projects travelled primarily through word-of-mouth and messenger bicyclists. The largest open source project had three users and two developers. I think it involved a lot of twine and glitter.
  • Make your users first time as easy as possible: Minimize perceived risk to maximize momentum.
  • Be an Open Source Gangster: Every day I'm Open Sourcin'.
  • Engage your community and recruit actively: Github, Twitter, Mailing list(s); whatever works.
  • Create a Github organization for large projects: Remember to tell a cohesive story.