I’ve spent several unproductive hours trying to rebuild an installation of Lazarus, the cross-platform Free Pascal IDE. Lazarus installs and works fine out of the box, but adding a new component package requires a rebuild, and this is the point where things come unstuck. Repeatedly unstuck, despite aggressive uninstallation, re-installation and trawling forums for help.

I have enough geek genes to resolve most issues, and I’ll nail this one too: but it shouldn’t have to be this difficult. The threads I’ve found with similar problems suggest these issues are not uncommon, but there’s a lack of authoritative documentation on overcoming them. This seems to be typical of many open source projects, but it doesn’t have to be that way.

A lot of open source tools provide excellent documentation, but there are still too many project teams which seem ambivalent about letting the great unwashed in on the fun. Yes, I know that when you’ve got your developer hat on, the thought of writing user documentation can seem, well … nah. But that’s no excuse.

There are too many exciting projects which suffer poor or non-existent documentation and successfully avoid mass adoption as a result. If you ever catch me doing this, kick me unmercifully. Please.