The problem with Drupal documentation

First things first: I've you've ever looked at Acquia's documentation, read this post and take the survey. You're welcome, jam. ;)

Now, a confession: I went to the Drupal.org documentation sprint at DrupalCon. And I tried to be useful, really I did. But I found myself frustrated, unable to really engage in it, and left mid-day feeling horribly guilty. Why? I think there were two causes:

1. The task is so immense. Drupal.org's documentation has grown like topsy, and now useful information is dispersed throughout several unconnected areas. The search function is really all that brings them together.
2. Quality varies wildly. The biggest sin is, as usual, too much writing. As I often say, writing is easy; editing is hard. Brevity is the soul of wit. Your mama wears combat boots. And so forth.

I wrestled with the task facing doc team lead Addison Berry: What would I do in her place? My answer surprised me: I'd burn it all down and start again.

I'm reminded of the real-estate markets of Detroit, Cleveland, and Buffalo. In those cities there are blocks full of houses that are worth less than nothing: They're too dilapidated to restore, and the cost to demolish them (about $8,000) is greater than the land's value. And ashes are cheaper to truck away than lumber, even if the burning dumps toxins in the soil.

What "city blocks" on Drupal.org are like that?

Such arson is unlikely to happen on Drupal.org. For one thing, it's discouraging to sweat out a long document, and then discover that it's disappeared. How many people would stop contributing documentation as a result? How would the community's soil be poisoned?

I'd still recommend cutting mercilessly. I believe at least 75% of the words on Drupal.org could and should be lost. But who would do the cutting? It's tough work, and without glory. Converting Drupal.org's documentation into a wiki(-like) format might help "crowdsource" the task. Or maybe not. Nobody likes to cut. Editing is hard.

Which leads us back to Acquia.

Acquia is a "third-party documentation provider", like the Lullabots and GotDrupal and DrupalTherapy and many others... and me. It's tempting to say that we thrive because of the weaknesses in Drupal.org -- that is, that they create a vacuum that we fill -- but it's not really true. After all, Apple's documentation is pretty good, but that supports outside writers rather than cannabilizing their work. In a healthy project, there's always a new audience to reach.

But we outside doc providers have an advantage over Drupal.org: a clear field. Arson is unnecessary, and will put no toxins in the soil. Each building we create on these virgin plots can reflect a different architecture, each fitting a distinct family of users.

That's why I think it's great that the Lullabots' CCK and Views videos will be available alongside my own: Theirs reach a certain audience, while mine will reach a different audience. And both of us can only do what we do because of the base provided by Drupal.org's documentation. Together -- we outside doc providers and Drupal.org -- we all grow the Drupalsphere.