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 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 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? Submit an issue here thechangelog/ping. That's our defacto list to work from and each week we promote things submitted on the blog, Twitter, or even the podcast! It's also open to the community as well, so folks can step in and ask questions too.
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.