Open Source Documentation, what?
The technology is there to make it very easy for an open source project to document. Wiki’s, blogs, web access to revision control software, but, documentation is usually done as an afterthought, or worse, left up to the people that may not completely understand the product.
I have written technical documentation many times in my life and I evaluate a lot of open source projects to see if they fit into our organization and I can tell you, a large percentage of the documentation for many open source projects is extremely bad.
A recent project that we started to evaluate had configs on their web site documentation, which was powered by a wiki, that directly contradicted their mailing list responses from the company. Thirty seconds later and I was able to correct the documentation to reflect the right information, but, that post which was 3 months old and directly referenced the incorrect wiki page never elicited an update.
Open Source Project maintainers — if you want people to use your product, you MUST provide good documentation. Samples of config files with quick comments about usability are a start if you’re not going to completely document the required config files, but, a project with little to no documentation will not get adopted by the masses.
While I appreciate the fact that the coders don’t like to write documentation, if you are going to publish a project and expect people to use it, take some time to write some documentation. When someone suggests changes or makes modifications to the wiki, be receptive rather than adversarial.
Your project will succeed much more quickly.
Also, if you have a commercial support package, and while I’m beta testing some software, I am also testing your support team’s attitude. I know the same guys hanging out on irc, monitoring the mailing list and responding to bug and feature inquiries are the same people I’m going to be contacting for support. Treat me wrong and I’ll find another solution.
Monetizing GPLed software isn’t easy — I know that. But make it easy for those of us that will end up relying on your solution and are willing to pay for a support contract to make sure we get the support we need.