Although adoption of Open Source software is growing, three things are generally considered to be holding it back:
- No commercial support
- Clunky user interfaces
- Poor documentation
The first one is usually available from third-parties, the second one is usually because developers are largely developing for their own benefit (and so know the way around their own UI) but the third one is a killer.
Take, for example, the Planet Planet project. The entire project description is two short sentences, which does cover the basic “What does it do?” question, but doesn’t go any further. Reading the rest of the page, you find out it’s written in Python, but that’s where the documentation ends. To find out anything more about the project (configuration file format, capabilities, etc.) you need to download the entire source code and pick through it yourself. Hardly user-friendly, given that the first thing a lot of people do when faced with a problem is hit the search engines.
It gets better with the Planet Venus fork of the project. They have the documentation available online, so you can see what you’re getting before you download it. One major omission (IMHO) is what the fork is/was all about – it’s advertised as a ‘radical refactoring’ of the original Planet code, but doesn’t actually say what’s changed and why it should be used instead of the original codebase.
So, when faced with the choice between the two projects (as I am) there’s nothing really to help me make the decision. I’ll probably go with the original codebase, given that forks have a habit of either dying or getting merged back in, and that there seems to be some big names using it (in Debian we trust), but I don’t like the fact that I can’t make an informed decision. Downloading both and trying them really isn’t an option with the deadlines I have.
So, if you’re going to create an Open Source project, please take some time to write project documentation. Put a full description of what the software is and what it does on the project homepage. Clearly list any software/hardware requirements. Make the documentation available online, including configuration examples. The more someone knows about the project before they install, the more likely they are to install (or, at least, to keep the install).