Everything about Ruby Midwest a week ago in Kansas City was very well done. In addition to the many useful presentations on the latest developments in Ruby and related technologies we heard a lot about the social aspects of open source.
Chris Wanstrath of GitHub (aka defunkt) started the conference with a keynote about making OS presentable, not regrettable.
I thought it was worth recording the points he made. My notes on his talk are below. Any errors can be blamed on me and my transcription of the talk.
Ruby Midwest Keynote 16 July 2010
The social aspect of an OSS project is often bad even when the code is good. Maybe it's too easy to release open source software. The Perl community does a good job managing this and we can learn from them. Good examples of Ruby projects are ClickToFlash and Homebrew.
Keep in mind the rules listed here whenever you release software. How do you determine if a project is 'released'? If you have a readme with install instructions your project is released, nor just shared or distributed.
Things every released project must have/do:
1. A license file, to show that it is open source.
2. Easy and reliable installation instructions. A quickstart procedure is most important to ensure adoption. This is an important part of MySQL's success -- Postgres has much lower adoption because its installation is much more difficult. Also important is reducing conflict so quickstart will work the first time: JQuery no-conflict mode made it easy to try along with other JS libraries when JQuery was new. If your project is intended for general use, make it easy for even non-Rubyists to install. Redis, for example, is very easy to install. [gh note: Here's an example of a project that needs work to appeal to non-Rubyists.]
3. Who is your API for? Machines or people? If you have a command line interface, you have a human API. Probably you should have a CLI to make it very easy for people to start using your code.
4. Provide examples. Good ones! ASIHTTRequest library for iPhone is good at this: All common tasks have examples.
5. Have a public API that does not change. The code behind the API changes but the API does not. Rdoc is not a public API. It's a method list.
6. Have man pages. Debian considers software without man page to be a bug. Many man formats can be used. Try Ronn to convert markdown to roff.
7. Provide a list of dependencies. If you need Bundler, say so.
8. Set user expectations. How do they know what it should do? Redis is good at this.
9. It's OK to stop maintaining a project, as long as you say so at the top of the readme.
10. It's OK if it's not actually used anywhere, even by you, if you say so at the top of the readme.
11. Provide the right number of features. It's better to allow plugins than to include every possible feature but be sure to provide some way to find them in a forum or wiki.
12. Lack of competition is a very bad thing. If someone else's library doesn't do what you want write your own small, focused app. For example: DelayedJob and Resque.
13. Don't do too few releases or too many releases. Make it easy to fix things quickly and release quickly.
14. Provide a change log, not just a git commit list. Note that Hoe can automate this.
15. See Tom Preston-Werner's article on how to do semantic versioning. God 0.12 is a very bad example. Is your project beta or production? If it's in production anywhere it's not beta!
16. Readme should include meta-info like how to get help, how to contribute, how to run tests. Keep it up to date and remember beginners.
17. Be a lazy maintainer. Provide a road map of things you want to do and others may write them for you. One project where this worked well was Scott Chacon's Showoff.
18. Avoid linkrot. This is why you don't use blogs as documentation. Redis has a good and downloadable wiki.
19. Don't have your own domain name unless it's a really big project [gh note: And even if it is a big project, don't do this.] Keep it in GitHub so it's findable and maintained.
20. When naming your project, google it first to see if it is distinctive enough but not too distinctive. Resque, for example, should be a distinctive name but it's screwed up by Google search.
21. Market it. Promote the fundamental feature of the app and let people discover the rest. A good example of this was the 'write a blog in 15 minutes' video in early Rails days. Good marketing examples to follow: Rails, JQuery, Redis, HomeBrew, Django, Unicorn, ASIHTTPrequest.