Top Five Open Source Project Mistakes

I spotted titus' piece yesterday, and I couldn't help but both agree and disagree with it in my own way. He covers a lot of the issues I usually come up against when looking at Open Source stuff, but I have a short list of recurring mistakes I see in one project after another:

Using Pet SCM Tools

If you're going to use non-mainstream stuff like darcs or monotone to manage your code repository, please make daily tarballs available instead of forcing would-be users to install and learn tools they would otherwise not even touch.

Like titus says, the barrier of entry for developers is paramount, and there are a lot of developers out there that don't want (or can't) use anything other than CVS or Subversion, either due to lack of will or lack of time to cope with the differences.

And even those that may already have the right SCM are likely to be somewhere behind a corporate firewall that won't let anything but HTTP through, so a tarball is the easiest way for them to pick up your code and run with it in under fifteen minutes.

Linux Myopia

One of the things that irks me the most when trying to get anything running on non-Linux UNIXes is the reliance on funky bleeding-edge libraries, hard-coded build/include paths or code that relies on what an int looks like on Intel machines.

I've been down that path for years in several directions (trying to port Sun stuff to BSD and Linux, trying to port Linux stuff to Cygwin and now trying to port stuff to Mac OS X), and it never ceases to amaze me how much of what Linux people take for granted is unique to their userland and to common distributions' packaging choices.

Although there are plenty of "common" generic libraries inside both Fink and DarwinPorts, it is a right pain to have to hunt down (and often recompile or port) the ones I need when a bit more care on the developer's side would make it a lot easier...

An offshoot from the above that has begun to take a prominent role as new languages and frameworks spring into existence is the "obscure pet library" or the "obscure build framework" angle.

Sometimes projects will adopt a base library/UI toolkit/database engine/scripting language/tool because they "like them", with utter disregard to whether or not it's actually easy to a) find and b) get running, and this can prove to be more challenging than the developers' ever thought (or seem to care) about.

And the interesting thing is that this is valid even across Linux distributions, with people relying on stuff that is either not part of another camp's distribution or completely arcane versions (I once had to track down a very specific minor version of a database library because some idiot had wrapped a custom build system that relied on parsing bits off the header files, etc.).

Other usual suspects are Jam (which I happen to know about due to my having used Perforce and OpenBeOS stuff in the past), ant (which I personally loathe due to its baroque underpinnings) and (fortunately mostly extinct by now) platform-specific dialects of make.

I honestly don't get the allure of the ubiquitous phpBB-based forum - it is both a mess to navigate and an eyesore when left to the dogs (all of them seem to devolve fairly quickly into grotesque animated signature contests).

Besides the graphical overload, search facilities are usually pitiful, making it impossible to find any sort of information easily unless it happens to be popular (in which someone will bump the thread) or specific enough.

Mailing-lists (with corresponding web-based archives) are easier to search (you can do it locally in your mail client or use Google), have a much better signal-to-noise ratio (at least developer mailing-lists) and can be followed off-line.

I've left this for last because titus has implicitly covered it throughout his post, but it is nevertheless part of my Top 5 for one reason alone:

A lot of developers hold the belief that "documentation" is using JavaDoc (or their favorite language's analog) to generate hideous frame-based sites in homage to MSDN class references, and insult their prospective users/co-developers by shipping the generic README and INSTALL files with their source distribution.

Writing a minimal setup guide listing the dependencies, typical configuration steps, testing, etc. is beneath them, and they'll just cry "look at the source!" if you dare post a simple question on their forum - in which, of course, you have to register as n00b.

That's pretty much it - seasoned developers will have noticed I have completely skirted the issues related to build systems, unit testing and bad UI design, plus - why not - actually picking a decent name for your project, but I think those issues we can leave out of the Top 5.

If I ever wrote a Top 10, however, they'd be in there for sure - right after crummy project logos...

Update: Removed Unicode characters that were throwing off indexing.