Apologies for the loaded headline. It’s a hat tip to the Twitter how-to articles that taught us the benefits of setting our avatars, writing a witty bios, setting a location, engaging your audience, and oh yeah, adding value. As a team that digs through a mountain of open source projects each week, so that you don’t have to, we’ve learned some concrete ways to build a community around your codez. Here’s our top ten list of things you can do to promote your Open Source project, or ten reasons I don’t fork your project.

1. You don’t have a friggin’ Readme

For a lot of projects, especially those hosted on GitHub, the Readme is often the first look someone has at your project. Tom Preston-Warner says the Readme is so important that you should write it first. I’ve started doing this for recent projects and have found it focuses my thinking and helps me communicate project goals to others. GitHub’s support for Markdown, Textile, RDoc, and others means rich formatted Readme files that can contain links, tables, and code snippets.

So what makes a good Readme? Here are some critical items you should consider:

  • Description – I’m surprised at how many times I land on a project page that is obviously popular (because Twitter told me so) but I have no idea why because the project owners don’t tell me plainly what the project is or why I should care.
  • Installation instructions – Tell me where to get the bits and how to install them
  • Where to get help – Link to the docs, mailing list, wiki, etc.
  • Contribution guidelines – Tell me how I can help out including wanted features and code standards
  • Contributor list – List the humans behind the project
  • Credits, Inspiration, Alternatives – Tell me if this is a fork of or otherwise inspired by another project. I won’t think you’re a douche when I find out later.

2. You don’t include tests, specs, features, examples

A project without tests is harder to trust, contribute to, and looks more like a hobbyish hack. More than that, though, tests cut down on support requests. I don’t have to ask you or Google, I can look at the codez. An examples folder with scenario-based code show me rather than telling me.

3. You have no project home page

As good as GitHub’s project pages are, they suck for SEO and branding. Create an attention-getting project home page. The GitHub Pages feature makes it dead simple to create simple project home page complete with custom domain support.

4. You need design help

If you’re not blessed with pixel-fu, find a designer who is and pay, trade, or barter with them to give your project an attractive brand and style. Stay away from contests and other “crowd sourcing” sites. Say no to spec work because you wouldn’t want to code a project for someone in hopes your code would be “selected.”

5. You don’t have a domain name

A nice looking home page is nice, but why not shell out ten bucks and make it easier for folks to find it? If the .com is not available for you project name, try a service like Domai.nr to find a creative alternative. We used Domai.nr to find the lg.gd short domain for our ‘logged links’.

6. You don’t have a Twitter Account

You’re probably already using Twitter to spread the word about your projects, but have you considered a dedicated project account? Erik Michaels-Ober creatively snagged the @gem username for the Ruby Twitter Gem, from which we post updates and answer support questions. @modernizr, @mongodb, and @octokit are other examples. Even if you’re not the project owner, perhaps you could create an unofficial account to help evangelize the project, like Trevor Burnham did with @CoffeeScript.

7. Your licensing is unclear

Just because code is published online doesn’t mean it’s free for the taking in the public domain. For me to use your code, I need to know the stipulations for doing so. Make it easy for me to know the terms under which I can use it by including a LICENSE file or section in the Readme.

8. You don’t reach out to me

Twitter lets you follow people in your niche easily, but perhaps the greater power is the ability to follow a topic. Search for and follow the hashtags related to your project. Find people asking questions or expressing frustration with problems that your project aims to solve. Chris Eppstein and I often reach out to people with #CSS3 questions and extol the benefits of Compass’ CSS3 module.

If your project is large enough, consider creating your own IRC channel. #node.js and #redis, are great examples of active, project-focused channels.

9. You don’t speak about your project at conferences and meetups

Nothing gives the illusion of expertise like a six inch elevated stage and a lanyard. If you want to grab the attention of potential users and contributors, submit a talk to conferences or meetups in your technology community. If you don’t get accepted, go anyway and organize a birds-of-a-feather session where you can meet personally with users, answer questions, and get feedback.

10. You didn’t submit it to The Changelog

If you want to tell the world about your new open source code hotness, one of the best venues is this blog. We strive to stay on the bleeding edge of open source, but we can’t find everything. Want to announce your new project? Ping us on Twitter or drop us an email.

Your turn

Now it’s your turn. We’d like to know what makes you follow and participate in on open source project. Tell us on Hacker News.

SPECIAL THANKS to Dan Benjamin and Jason Seifer over at The Dev Show (we’re friends of the show) for an honorable mention of this post on today’s show.


Have comments? Send a tweet to @TheChangelog on Twitter.

Subscribe to The Changelog Weekly – our weekly email covering everything that hits our open source radar.