Why is it that the Drupal documentation is so bad?  Well, perhaps that is an overstatement.  There are many people who put a lot of work into the documentation on drupal.org.  Still, it's very confusing from the outset to try to learn Drupal.  I've seen this commented on a number of times and given it quite a lot of thought myself now.  I joined the Drupal documentation team to see what I could do about it, and have made some contributions now myself.

But why doesn't everyone contribute documentation?  Why aren't people motivated to write documentation?  Well think about this: If I spend 10 hours learning a feature in Drupal, then as a consultant, I am now more valuable because I've learned a new skill.  If I spend my time on improving core, then because Drupal becomes a better product, more people will want to use it, and again my skills are more valuable based solely on the laws of supply and demand.  Now, I do believe that there are things people do without seeking financial benefit in return.  But I don't believe that writing documentation for a content management system, even if it is the greatest in the world, is one of those things.

So why do people write documentation?

Well the best documentation out there is books.. and authors make money for those books.

Great content can be found in blogs.  Blogs may be written for several reasons, but essentially they are for some kind of self promotion, which lets face it, we all hope will lead to monetary gain.

Perhaps this all sounds a little cynical.  Perhaps I should have more good faith and the drupal community.  But let's face it, we're pretty much all in it for the money.

So what do we do about it?  Well, we still need more documentation contributors.  We still need better documentation for drupal.  So what then, are the business benefits of writing documentation?

1. If Drupal grows, everybody wins.
One of the biggest reasons that more people don't come to drupal, is that it is initially very intimidating.  I've lost count of how many times I've read in twitter and in blog posts, that drupal has a steep learning curve.  And to be certain, it does.  But if you are truly a drupal expert, then more people coming into drupal should not worry you. There will always be plenty of work for skilled drupal developers, no matter how easy it gets to learn the basics.  So now, with drupal 7 on the rise with all of its usability enhancements, and with more and more people realizing how important it is to have a good content management system, Drupal will absolutely contine to grow. The better the documentation is though, the better chance we will have of outdoing the competition.  This means more people will be moving to drupal from other content management systems, and people looking to set up new sites will be much more likely to choose Drupal.  While some may choose to go it alone (because the documentation is so great and it seems so easy), There will be even more people looking for a quick start and willing to pay an experienced developer to do the work.

2. Drupal is a meritocracy. 
This means that the more you contribute to Drupal and it's community, the higher you are valued within the community.  If you are seen as an expert, you are worth more money.

3. Writing documentation forces you the learn a subject thoroughly enough to put thoughts on paper (or pixels). This takes more effort than simply understanding the concepts yourself, but the understanding you will gain from it is well worth it.

So now with all excuses gone, get to it.. go write a documentation page:
http://www.drupal.org/handbooks