The documentation problem

Submitted by Larry on 22 April 2007 - 11:36pm

Over on the Planet, someone posted a link to a budding Drupal user who was having the usual first-time-user troubles. "I want to do X, Y, Z, but I can't figure out how and no one will tell me, help!" Been there, done that, I suppose. But how can that be if there's so much Drupal documentation? Simple. The questions most people ask are the hardest to answer, because there isn't just one kind of documentation.

  1. Beginner documentation. This is the proverbial "this is a mouse" documentation. For Drupal, this would be the "this is what a node is" and "Drupal calls its categories 'taxonomies' because it's more powerful than a linear category list" type information.
  2. Expert Reference documentation. These docs are aimed at people who already know what they're doing, but don't remember all the details. This is mostly reference documentation, API documentation, and so forth.
  3. Training documentation. These are the docs to help push people up the learning curve. The goal here is to show someone who knows what a node is and what taxonomies are the 50 ways to put them together to build all kinds of cool sites; it's to coax people to learn Views and CCK and save themselves hours of time, but that means teaching them the myriad ways to not only use those modules but use them well and "with the grain".

The basic problem is that type 3 is hard to write. Really hard. The best people to write it are those who have only just passed the "I kick ass" threshold (see link above), because it's still fresh in their mind. They're still excited about it. They still remember their "ah ha!" moment. Those people also do not last very long, because once they get past that hump they tend to become self-training and are far more interested in learning new things than writing up the things they just learned.

Even then, writing good documentation is a lot harder than many people realize; that's why most major open source projects have dedicated documentation teams. People who can write great PHP can't always write great PHP documentation, to say nothing of application documentation. There's nothing unique to open source about that, or even to technology. For many tasks, too, it is impossible to teach or train something without practice. Lots of it. Software is no different.

The same holds true for "informal documentation", that is, forum posts, mailing lists, IRC channels, and so on. Generally it's easy to tell if someone asking a question is at the "this is a mouse" level or not. Those questions are usually easy to answer briefly, frequently with a reference to where more detailed Beginner Documentation can be found (with or without the infamous "RTFM"). The problem comes when the person is clueful. It's not always easy to tell if someone is at stage 2 (intermediate and learning) or stage 3 ("I kick ass"). Very often, they can be at both on different topics. I know I am. But how does one answer questions that fall into that range?

One could answer with "Use X, Y, and Z" and assume the person is clueful enough that, pointed towards module X, code snippet Y, nifty suggestion Z, they'll be able to put 2+2+2 together and get 6 on their own. Alternatively, one could answer with a detailed description of X, a complete explanation of Y, and the history of when one used Z and came up with that nifty idea. The second answer here is documentation type 3, the "training documentation".

For the person answering, though, "Use X Y, and Z" takes about 2 minutes to write/say/type. The more detailed explanation could take 2 hours, depending on how detailed they want to get and how quick on the uptake the person asking is. That's why you'll almost always get the simple answer first, regardless of whether you're dealing with Open Source or proprietary software. Yes, that answer is targeted at "someone who already knows what they're doing", but that doesn't make it useless. That makes it time-efficient for the person answering which, if the person answering is a volunteer, is of paramount importance. Sometimes if you ask nicely you'll get the long answer, but people don't always have the time to do so even if they are so inclined. Answering the long version multiple times also gets very tiresome after the first few times, so people are less likely to take the time to hand-hold a new person just like they hand-held the eight before them.

There is also the challenge of avoiding duplication. In a hyperlinked online world, saying the same thing twice is a crime against nature. One never teaches a man to fish multiple times. One does so once and then makes a link to it. It would be a waste of bits for instructions on "how do setup and configure module Foo" to include a description of what a module is, how modules fit into Drupal's architecture, the four different places that modules can be placed and the pros and cons of each, and what a "directory" is in Unix in the first place. The module documentation, and the person writing it, have to assume that the person reading it already has a given threshold of competence with the system or else they'd become useless. That is frequently not explicitly stated, but is true of all documentation for any subject, technology or otherwise.

I've seen this sort of pattern in multiple venues, and have been on both sides of it. It is not open source people being mean or lazy; it's open source people being efficient. Of course, it's efficient for themselves, not for the person asking a question. And why should they be efficient for the person asking when they don't know that person at all, answering that person the long way could be a waste of time, and doing so doesn't get them anything besides a warm and fuzzy feeling and being late for dinner?

That's why the most important form of documentation, training documentation, is so commonly missing from software, Open Source or otherwise. The best way to get it is either taking the time to experiment personally and acquire it yourself, to ask really nicely and hope you find someone with spare time on their hands to give the long answer, or to make it worth someone's while to give you the long answer.

That's called books. I have a copy on order, as much to support the authors for taking the time to write training documentation as because I need it myself (although I've no doubt I'll learn something from it myself).

Ray (not verified)

23 April 2007 - 6:47am


Nice analysis of the situation. I'm new to Drupal and have made the commitment to climb the curve. Do you think some sort of Wikipedia-style documentation might work? The current Handbook system seems a little clunky.


skor (not verified)

23 April 2007 - 11:18am

In reply to by Ray (not verified)

Think a page is missing from the current documentation?
Create Content> Book page

Think a page needs an update?
Scroll to the bottom and click Add Comment. For extra credit, file a doc issue and get your comment incorporated quicker.

It's really not that hard.


23 April 2007 - 2:01pm

In reply to by Ray (not verified)

The Drupal handbooks are already, IMO, better than a wiki. They're reasonably publicly editable, but you get the advantage of a real hierarchy of information rather than the disorganized blob of a wiki. You also don't need to learn yet another obscure proprietary language.

The main difference is that global-edit powers are restricted to a smaller number of people; That's a good thing, because technical docs generally do have a clear "right" and "wrong" answer to many subjects, and you don't want any random user able to edit, say, the "What Drupal is good for" or the Drupal history page.