In Tom Geller’s recent grumble about the official Drupal Handbooks on Drupal.org, he notes a problem (the tree of docs is huge and is difficult to reorganize or prune) but — like most of the rest of us — he isn’t quite certain how to solve it. So he offers a prayer to the gods of WIkipedia, as so many have done before:

Converting Drupal.org’s documentation into a wiki(-like) format might help “crowdsource” the task.

Funny thing about this recommendation, which all of us have been tempted to issue at one time or another: The docs are in a “wiki-like format”. Any registered user on Drupal.org can edit a page. All of its revisions are accessible. You can show diffs between revisions.

And yet the problem is not solved. The Drupal docs are still nowhere near as good as a wiki. Or — important distinction — they are nowhere near as good as Wikipedia, which is what most people think of when they think of a wiki.

You can’t spell Wikipedia without “Pedia”

But Wikipedia is not the typical wiki. (My impression is that the average wiki on the Internet kind of sucks — the Rails wiki, for example, was legendarily disorganized and out of date until recently.)

Wikipedia’s secret is that it isn’t just a wiki. It’s an encyclopedia, an old and familiar genre with well-understood semantics. When you see a Wikipedia link to a term like “bluegrass music”, you see more than just a link: You already know what is on the other end.

• The topic of the article is more-or-less completely defined by the title of the link.

• The entry will be written for a general audience and will not contain excessive detail or be too long.

• The entry may relate to other entries, but is designed to stand alone. No prerequisites will be assumed.

It is this implicit context that makes WIkipedia so usable. That’s why you can read a Wikipedia page filled with hundreds of internal WIkipedia links and not get lost. You know what each of those links are. And that’s why each external link gets special formatting on Wikipedia: It’s a warning. “This is not like the other links; you don’t know what’s out there. Prepare to be rickrolled.”

The encyclopedia is flat

One of Wikipedia’s other friendly features is that the Wikipedia architecture is a big flat list. True, there are “superarticles”, like disambiguation pages. And there are pages with subtopics. But there are very few special structures for creating such pages, and no real provision at all for creating trees with formally defined “parent” pages and “child” pages. So, nobody does that.

This is great because it frees people from worrying about organization. You can start a new Wikipedia article by searching for the intended title and clicking “create the article”. No need to worry about where it fits in some grand Wikipedia schema. No need to figure out how to edit the Music category to indicate that progressive bluegrass is a kind of bluegrass. No need to figure out what kind of music the Flecktones play. (Is “blu-bop” a real word? It is now!)

There is also no danger of accidentally creating two entries for the term “bluegrass music”.

A Wikipedia editor only needs to edit the content. A Drupal handbook editor must not only edit the content but also arrange it in a structure. That’s a whole new level of difficulty and intimidation.

What does this mean for Drupal?

It would actually be really nice to have a Drupal Encyclopedia — a collection of pages, designed to be read independently, which each cover a single topic in encyclopedia fashion for a general audience.

But, as a general-purpose organizational scheme for the Handbooks, the encyclopedia model doesn’t work. Sometimes the Handbooks need to contain pages with obsessively detailed instructions. Sometimes we need explanations of complex topics that go on for more than one page and need to be read in order. Often it’s impossible to capture a page’s entire context in its title, so we need to organize pages into topical sections and subsections and chapters and books.

In other words, WIkipedia’s design is not a silver bullet. We’re not trying to write an encyclopedia. We’re trying to write something different, and more complicated. No wonder it’s so much harder to get right.