Documentation Is Part of the Project Too!

Over the years, I've used a lot of open source software, and during that time a common theme has emerged. Open source developers are great coders, but overall, the standard of the user documentation can leave much to be desired!

True story: I was once commissioned to write an article for a magazine showing how to install an open source personal automated IP telephony package. The software itself had lots of dependencies, which I dutifully downloaded, complied and installed. Then, at around 4am and about 75% of the way through, the documenter seemed to have become bored. He ended the documentation with a phrase like: "There are a bunch of other things you'll probably need to do to get this running..." What the f**k...? That's not documentation; it's a joke.

Much more common are user guides and other documentation that are simply out of date. When a new release means changes to the way you install or use the software, the instructions need updating. They are a VITAL part of that release. People do not have time to plough through your code trying to work out what the hell you mean. We are not mind readers. We are your users. Trying to get software to run is not the object of the exercise: using it to complete a task is.

I fully realise and applaud the fact that the open source business model involves allowing the software to get to whomever can benefit from it, and to charge for consultancy, customisation and books showing how to go deeper, but come on: basic documentation is the difference between an enthusiastic user buying your time or books and thinking your stuff is the worst piece of digital excrement ever to stink up a hard drive.
 Thank you.