This is how I want all project web sites to look…

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: 
  • DON’T require me to understand how something like Trac or some other tool works in order to get at the information about your software project. Navigation should not assume I’m a developer, it should assume I’m a prospective user who will leave if they can’t read the menu. If you want to use a project management tool to do your work, more power to you, but as a prospective customer, it’s none of my business — don’t drag me into your personal hell! I just want the software! 
  • DON’T be satisfied with the Sourceforge page as your project’s “homepage”. The problem with doing that is twofold: first, Sourceforge kinda sucks, and occasionally becomes unusable. Second, it doesn’t provide a simple way for you to give me information, nor a simple way for me to find it even if you produce said information using their tools. Also, it’s bad form. If you haven’t committed to the project enough to give it a proper site, well… 
  • DON’T put some kind of “Coming Soon” page with a bunch of information with *NO DATE*, because I’m going to go ahead and assume that this thing is vaporware, and that the “coming soon” post is 3 years old. Nothing in this world is more annoying than time-sensitive information being plastered on a web site with no date. 
  • DO NOT — I repeat — DO NOT force me to download a 20MB tarball to get at the documentation. That’s not how things work. I get to see what I’m downloading *before* I download it. You’ll save me some time, and save yourself some bandwidth, and you’ll have more accurate statistics about how many people download and use your software, because the numbers won’t be skewed by folks who were forced to download the package to get at the documentation. 
All of that said, I probably won’t use CouchDB, even though I love their project’s site. Javascript makes my brain explode, so mixing them with something like a database, which to me is the digital embodiment of sanity itself, is… insane. But if you’re someone who can deal with this concoction, I encourage you to check out CouchDB — at the very least, you can figure out if it might be a fit for you without clicking from their home page a single time. That just rocks. 
  • deepspawn

    I have to agree on most of what you have written here, technically I try to avoid using any piece of software that has an ugly webpage including it’s design.

    There are few exceptions where you already now it’s a great piece of software so you bypass the webpage judgement.

  • bignose

    Good list. I’d add:

    Tell me the license the software is released under, right on the front page. If you’re making free software, *tell me* so I can quickly be interested in your project.

  • Pádraig Brady

    Very good point. Most project pages are very difficult to parse.
    My own was terrible until many people complained and I
    forced myself to think like a user for a while to see what they would want.
    It probably still is lacking, so I’d be interested in any suggestions:

    An architectural drawing is a good idea. I’ll add that soon.
    Also I must add a “homepage accessibility” metric to my open source openness score:

  • andymurd

    Sourceforge just doesn’t cut the mustard any more and I don’t think that Google Code does either (although it is an improvement). It shouldn’t be too hard for maintainers of both sites to make the improvements you talk about before someone else eats their lunch.

  • yoursite

    What gets me is your site. I hate wordpress sites. Why do they appear as a small long collum in the middle of my massive screen. its so annoying. at least half of my screen is displaying nothing on your site. grrr.

  • nogg3r5

    I have hte same kinds of problems with projects/software websites. The things I like to know are:

    Where can I download it from? I dont wanna hunt for a downloads page, I want a link, on the front page, preferably a big one. Sometimes I already know all about the software and I just wanna hit a button and download it.

    What OS does the software work on? I use windows OS X and Linux, So I like things that run on all three. I dislike it when im on a windows box and I download stuff that I cant use, likewise for Linux and OS X

    Other good things to have hanging around that you touched on are distribution rights, what language the code is, is it open source etc.

  • Jim Menard

    One feature I added to the DataVision ( site is a list of “competing” projects.

  • Rob

    I thought it was me. I’m a hardware guy transformed into a software guy and I thought those other project pages were some sort of standard way that everyone created their project site. Good to know that it wasn’t me and they are just flat out bad.

  • Robin

    @Pádraig Brady: A suggestion for your page. Describe what “lint” actually means. I’m not a native English speaker but consider myself “advanced” and I didn’t know what lint means until I looked it up just now (I’ve heard of pylint, but didn’t know what it really means).

  • JW

    I’ll add one more thing: screenshots are nice, even necessary on project websites. But videos don’t replace them! I have seen project websites with videos showcasing the application but without screenshots. But when I’m for example listening to music, I don’t want to stop my music to watch your video. I also don’t want to take 4 minutes to watch a lot of non-sense. I just want to get a quick look, so screenshots will do just fine, no need for videos.

  • Pingback: Interstellar Medium: the Free Software carnival » Free Software Carnival: 28 June – 4 July

  • Pingback: links for 2008-07-05 « Mike Does Tech

  • paket

    I would like to nominate PHPNuke ( as an example of a *bad* project page. Could someone please look at the page and tell me what it actually does? The term “Content Management System” means many different things to many different people and doesn’t actually differentiate your software from a bucket.

  • web design

    Thank you for pointing out that sourceforge pages suck, I’m not alone!

  • ernst doubt

    Stop whining. If you can’t figure out how to use trac or click on a few extra links to find something then what use are you to an opensource project? Most opensource projects don’t really *need* users, what would help more is extra developers. And people who can’t take an extra couple minutes to understand the navigation of a website (even if it falls in the category of “lame” according to your definition) probably aren’t going to end up being much use as developers. In my (never humble) estimation, this dumbing down of the internet is doing us all a disservice. Having clever users (who are not yet developers) confronted with trac isn’t an impediment. It’s actually a way for them to begin to understand the development process and perhaps think about participating at some point in the future. You do realize that your rigid specifications are completely arbitrary, right? And that there are a ton of other pedants out there who may disagree vehemently with some of your points (and have their own specific rules about what’s “acceptable”). My opinion is that annoying you (and the other 3-5% of the population who care about administrivia such as this) is just fine. Let the rest of the world have an opportunity to educate themselves rather than arguing for a dumbing down to the lowest common denominator in the service of laziness and impatience on your part.

  • Mike

    Hi. I like you post. I am the project leader of an open source java project, Architecture Rules. While developing the site I tried to put a lot of thought into what viewers were looking for and tried to address the issues that I saw with other sites.

    For example, at the header of every page of version one of the site I had paragraph that described the project, the language, the goal, the major dependency, and the license. This is version one of the site: “Assert Your Architecture! with this open source java library. Architecture Rules leverages an xml configuration file and optional programmatic configuration to assert your code’s architecture via unit tests or ant tasks. ”

    My biggest complaint is projects that don’t tell you what language it is for within the first sentence…

    If anyone is up for it, would you review my landing page and maybe a page deep and tell me if there is any missing critical information? Thanks!~

  • Randy J. Ray

    I really like the points you make, and the way you gather them together and expound on them clearly. I’ll be referring to this page in the future, as I revise existing pages and create new ones!

  • Pingback: links for 2008-07-06 « Breyten’s Dev Blog

  • WS

    Right on. I also get annoyed when I have to hunt around for information, or the description is too vague or too specific.

    @ernst doubt: even if you disagree with his specific points, you have to agree with the spirit of making project websites easy to use. You say that projects need more developers, not users, but I would think that many people would be users of a project before becoming a developer on it.

  • Steve Lee

    Great list and I agree, with the possible addition of webcasts these days.
    I really hate sites htat just have news on the home page that assume yo already know all about it.

    I just set up my Jambu web site trying to make it as informative as possible and found I just needed a little tweak with ideas from your list.

  • Joe Cascio

    @ernst_doubt So, by that rationale, you’d want your website to be as bad as possible so only the best developers would actually find their way through. I don’t think so.

    You’ll attract better developers with a better site because it saves them time and because a good developer will want to be associated with a quality project.

  • m0j0

    Hi all, just wanted to reply to some of these comments, since I left for a weekend away just after submitting this post 🙂

    A couple of posts talked specifically about “design”. To me that means fancy graphics and lots of attention paid to color schemes and stuff. I don’t know that I necessarily care about that. I mostly just care about getting at the information I want and having that information be easily consumed. I guess you could argue that good design helps there, but I’ve seen sites that are almost nothing but plain HTML that do the job. In fact, I seem to remember the Apache site being mostly HTML for a long time.

    As for PHP-Nuke, I would agree that from the perspective of someone who has never heard of the app before, going to that site would not do a lot to encourage me. However, that app is downloaded at least hundreds, if not thousands of times per day. Presumably a lot of that is due to word of mouth, so people just go and download it sight unseen. This has the unfortunate effect of making the site designers think they’re doing a super-fantastic job. Also, if you study that site for about a minute, you’ll see that they actually do have some of the information there, but it’s all out of order. In addition, I’ll also agree that PHP-Nuke should really just be called something like “article publishing website in a box”, because last I saw, it was not a CMS. There are a bunch of PHP applications that call themselves “Content Management Systems” because that’s what PHP/MySQL book authors in 2000-2001 called the little mini-project example, which built something not dissimilar to slashdot. In fact, the guy who started PHP-Nuke did so as a way to learn PHP. I don’t know if he knew what a CMS was either at that time.

    @ernst doubt – I’d reply to that classic “stop whining” post except that I’ve learned that I could write the most beautiful response, and at best it would just be whipped cream on top of a pile of steaming crap. Let’s not feed the trolls. I only approved the comment to see if there was any other hidden sentiment like it out there. Turns out there isn’t.

    @ everyone else, thanks a lot for the encouraging words. Glad you found my ramblings useful 😀