My brain has a set of rules that software project websites get tested against. Each time a project site fails to comply with a rule, I get ever-so-slightly more annoyed, and ever-so-slightly less likely to use the software in question (if there are alternatives, this is even maybe not so “slightly”).Â

I thought I’d list these rules because I suspect others are like me: we’re extremely busy, we work too many hours, and are involved with too many projects to spend hours trying to figure out what some piece of code someone mentioned once in IRC actually does.Â

But first, know that this site actually complies with just about every single rule there is, so it’s a great template to work from if your site needs brushing up.Â

First and foremost, tell me, right away, what this thing does, the problem it solves, and (at a high level) the approach taken to solve the problem.Â

Tell me the language it’s written in. If it’s open source, and it’s written in a language I hack in, *and* it solves a problem I need solved, maybe I can help out, or be encouraged that if something flakes, I can fix it, or at least speak the developer’s language if I have to describe the issue to the folks upstream.Â

Tell me what OS is required, and preferably what OS/version is tested with.Â

Give me a full list of dependencies with links to go get them, or give me a link to “Dependencies”, or to an install document that lists them.Â

Tell me the current version, and the date it was released. Beta versions and dates are nice too. If there is a timed release schedule, tell me that.Â

Keep the information up-to-date. I shouldn’t have to wonder if your software is going to work under OS X 10.5 or RHEL 5, or if your plugin will work under the latest version of Drupal/Django/Moodle/MySQL/Joomla/Firefox…

BONUS: a very simple architectural drawing that shows me exactly what components make up the whole. The one for CouchDB is as good as any I’ve ever seen (assuming it’s accurate).Â

BONUS: if screenshots are applicable, use them. They communicate a million times more information using a million times less real estate and bandwidth. They can communicate things you didn’t even know you were communicating. Of course, that could be good or bad, but it keeps you honest, and customers like that :-)Â

For kicks, here are a few things I see sometimes on project web sites that I wish they *wouldn’t* do:Â