Perusing new open source software projects has long been both a job requirement and a pastime for me. Over the past decade plus so I’ve come across a ton of open source project web sites, running the gamut from good to bad — with a healthy contingent of ugly in the mix.
Of course, it takes more than a sweet web site to make an open source project worth writing about or contributing to — a project that offers up a lousy solution to a real problem, or, worse, seeks to answer an unasked question has more fundamental issues to tackle. On the other hand, you could have a project ideal for scratching, elegantly, some global itch, but if the project does a poor job conveying its whys and hows, it could end up overlooked.
The basic information I look for in an open source project home page, either right up front or no more than one clearly-labeled link deep, fits (or, at least, can be made to fit) into the classic Five W’s (and an H) model:
What is the project about / what does it do / what is it for?
Pretty straightforward. If see a tweet from an open source savvy pal that says something low-context like, “really impressed with what they’ve got going on at $LINK,” and you click, it shouldn’t take long, at all, for you understand what the project is about.
Initially, I’d left mention of license till the bottom of this post, but for an open source project, that’s another “what” I like to see answered right up top: what’s the license?
Why should I care / use / contribute?
What is it and why should I care sort of go together: a first impressions one-two punch. OK, so I see that this project is (say) a command line to do manager. What makes this one better or different than the million other to do apps out there? A well-written “what is it” blurb ought also to answer the “why should I care” query.
Where do I get it (packages / binaries / source)?
All right, the project does X and does it in a way that seems sufficiently interesting. Where do I get it? If the project is packaged up for particular operating systems, which ones and where do I find those packages? Where’s the source?
How do I use it / get involved?
When I’ve gotten interested enough in a project to learn about what it’s supposed to do and where I can go to get it, I like to take it for a short spin. The most effective projects make it easy for users to get their feet wet by offering up some short getting started instructions.
Who’s working on the project, and how can I connect w/ them?
Over the past few years, when I come across a project that seems interesting, but perhaps not yet ready for prime time (or just to be useful to me), I scan the project site for the Twitter feeds or the blogs of the project’s key developers to follow or add to my RSS feed reader. Sometimes these links lead me to other interesting projects, and future tweets or blog posts serve to jog my memory about projects I’ve looked into but didn’t end up digging into in earnest.
When was the last release, repo activity, project update (proof of life / sell by date)?
The Internet is littered with the floating husks of dead open source projects, and depending on the web site, one’s slow-moving-but-not-dead project can look exactly like a project that’s gone, never to return. Abandoned projects tend not to be very interesting to me, but that doesn’t stop my friendly neighborhood search engine from suggesting them. When I’m checking out a project, I stay on the lookout for things like commit dates in source repositories, for release dates on binaries, and for mailing list activity. The best projects don’t make me dig for long.
Those are the basics I look for in an open source project web site, though there are other, specific details I like to see right up front, like the license a project uses. Is it something familiar, like GPL or Apache, or is it some wacky vanity spin of the MPL that requires careful reading before you get an idea of what is and isn’t allowed?
What do you look for in an open source project web site?