Documentation: the secret advantage of Open Source

Just like everyone else in the industry I had been preconditioned to believe the oh so logical argument that “Open Source is free, therefore it is unsupported, and so it is poorly documented. You are on your own.”

Guess what: WRONG!

How do I know? – Well, I recently had  to deal with a number of commercial (and ofter exorbitantly expensive) software packages form “well respected” enterprise vendors, and I caught myself longing for the clarity of the Open Source documentation and community support.

Having trouble believing me? Check PHP documentation and notice multiple examples.  Need something more “consumer-grade”? – Take a look at WordPress. Oh, wait a second, I am so sorry – there is no consumer documentation for WordPress, because it does not need any (documentation for the blog owners exceeds any expectations though).

In hindsight the cause is painfully obvious: a commercial product enjoys commercial support, which means that support is mostly a liability: the sale has happened, the customer is locked in, and, unless there is a major security leak making the front pages, a documentation hole or a bug gets scheduled to be fixed (or not) in the next release, months and months down the road.

In the Open Source world the projects are evaluated based on the strength of the community and documentation. You do not believe me? – Check out  (and bookmark it if you have any plans to use open source ever). Pay attention to the comments for each package and you will soon notice that there are four main themes:

  1. Will it work for me? – the answer is always the same: “depends on what you really need”
  2. Is it buggy?
  3. Is it easy to install and deploy?
  4. Is there a vibrant community?

If the answer to any two of those questions are negative, the project dies. If any one is “bad”, the project crawls along but there are very few new users. Strangely, the Open Source community lives according to the basic rules of fierce capitalist competition: each project strives to attract more users and developers, and the loosers die.

And so, if you have a problem with an Open Source product documentation, you do not have to call an underpaid, outsourced clueless “customer satisfaction executive” on the other side of the globe only to have him admit that “yes, there seems to be a problem”, and he will “escalate to the second level support” (where only the third level actually knows the product beyond reading the manual).

Instead you read the FAQs. You ask in the forums. You contact the developers. If everything else fails, you fix the problem yourself (yep, you have the power), and then you publish the solution (or a correction – no contribution is too small, everything counts toward a good karma).

You do it because the FAQs told you to. Because the forums are full of people who have done just that. And because other users will go out of their way to say “thank you” (and amazingly positive and reinforcing experience).

You do it because now you will have a reputation – that most precious commodity of them all, and next time you need help, you will get that extra bit or respect and a prompt answer from people who just a second earlier thought they were too busy today (only they simply cannot ignore a plea by someone who helps others like you do).
So, next time you choose a product, or a platform, think about it this way: do you have the budget  and the corporate power necessary to extract help from an entity that sees it as a not-so-necessary liability (and has cutting that cost as one of its official goals), or do you want to take your chances and throw your lot with a bunch of people living by one simple principle: “We are all in this together”…

I am back to Open Source.

About this entry