Top ten reasons why I won't use your open source project

Apologies for the loaded headline. It’s a hat tip to the Twitter how-to articles that taught us the benefits of setting an avatar, writing a witty bio, 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 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 our short domain.

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 Changelog News

If you want to tell the world about your new open source code hotness, one of the best venues is this website. We strive to stay on the bleeding edge of open source, but we can’t find everything. Want to announce your new project? Submit it [right here](https://changelog.com/news/submit).

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.