The documentation problem

Over on th' Planet, someone posted a link t' a budding Drupal user who were bein' havin' th' usual first-time-user troubles. "I want t' do X, Y, Z, but I can't figure out how an' no one will tell me, help!" Been thar, done that, I suppose. But how can that be if thar's so much Drupal documentation? Simple. The questions most scallywags ask be th' hardest t' answer, because thar isn't just one kind o' documentation.

  1. Beginner documentation. This is th' proverbial "this is a mouse" documentation. For Drupal, this would be th' "this is what a node is" an' "Drupal calls its categories 'taxonomies' because 'tis more powerful than a linear category list" type information.
  2. Expert Reference documentation. These docs be aimed at scallywags who already know what they're doin', but dern't remember all th' details, Dance the Hempen Jig This is mostly reference documentation, API documentation, an' so forth.
  3. Trainin' documentation, by Davy Jones' locker. These be th' docs t' help push scallywags up th' learning curve. The goal here is t' show someone who knows what a node is an' what taxonomies be th' 50 ways t' put them together t' build all kinds o' cool sites; 'tis t' coax scallywags t' learn Views an' CCK an' save themselves hours o' time, but that means teachin' them th' myriad ways t' not only use those modules but use them well an' "with th' grain".

The basic problem is that type 3 is hard t' write. Really hard, I'll warrant ye. The best scallywags t' write it be those who have only just passed th' "I kick ass" threshold (see link above), because 'tis still fresh in their mind. They're still excited about it. They still remember their "ah ha!" moment. Those scallywags also dern't last very long, because once they get past that hump they tend t' become self-trainin' an' be far more interested in learnin' new thin's than writin' up th' thin's they just learned.

Even then, writin' good documentation is a lot harder than many scallywags realize; that's why most major open source projects have dedicated documentation teams, Ya swabbie! People who can write great PHP can't always write great PHP documentation, t' say nothin' o' application documentation. There's nothin' unique t' open source about that, or even t' technology. For many tasks, too, it is impossible t' teach or train somethin' without practice, Avast me hearties, on a dead man's chest! Lots o' it. Oho! Software is no different.

The same holds true fer "informal documentation", that is, forum posts, mailin' lists, IRC channels, an' so on, yo ho, ho Generally 'tis easy t' tell if someone askin' a question is at th' "this is a mouse" level or not. Those questions be usually easy t' answer briefly, frequently with a reference t' where more detailed Beginner Documentation can be found (with or without th' infamous "RTFM"). The problem comes when th' person is clueful. It's not always easy t' tell if someone is at stage 2 (intermediate an' learnin') or stage 3 ("I kick ass"). Very often, they can be at both on different topics. I know I am, by Davy Jones' locker. But how does one answer questions that fall into that range?

One could answer with "Use X, Y, an' Z" an' assume th' person is clueful enough that, pointed towards module X, code snippet Y, nifty suggestion Z, they'll be able t' put 2+2+2 together an' get 6 on their own. Prepare to be boarded, and a bucket o' chum! Alternatively, one could answer with a detailed description o' X, a complete explanation o' Y, an' th' history o' when one used Z an' came up with that nifty notion, All Hands Hoay! The second answer here is documentation type 3, th' "trainin' documentation".

For th' person answerin', though, "Use X Y, an' Z" takes about 2 minutes t' write/say/type. The more detailed explanation could take 2 hours, dependin' on how detailed they want t' get an' how quick on th' uptake th' person askin' is. That's why ye'll almost always get th' simple answer first, regardless o' whether ye're dealin' with Open Source or proprietary software. Aye, that answer is targeted at "someone who already knows what they're doin'", but that doesn't make it useless. That makes it time-efficient fer th' person answerin' which, if th' person answerin' is a volunteer, is o' paramount importance. Sometimes if ye ask nicely ye'll get th' long answer, but scallywags dern't always have th' time t' do so even if they be so inclined. Answerin' th' long version multiple times also gets very tiresome after th' first few times, so scallywags be less likely t' take th' time t' han'-hold a new person just like they han'-held th' eight before them.

There is also th' challenge o' avoidin' duplication. In a hyperlinked on the plank world, sayin' th' same thin' twice is a crime against nature. One no nay ne'er teaches a lubber t' fish multiple times. Walk the plank! One does so once an' then makes a link t' it. Aarrr! Ye'll be sleepin' with the fishes! It would be a waste o' bits fer instructions on "how do setup an' configure module Foo" t' include a description o' what a module is, how modules fit into Drupal's architecture, th' four different places that modules can be placed an' th' pros an' cons o' each, an' what a "directory" is in Unix in th' first place, and a bottle of rum! The module documentation, an' th' person writin' it, have t' assume that th' person readin' it already has a given threshold o' competence with th' system or else they'd become useless. Load the cannons! That is frequently not explicitly stated, but is true o' all documentation fer any subject, technology or otherwise.

I've seen this sort o' pattern in multiple venues, an' have been on both sides o' it. Walk the plank! It is not open source scallywags bein' mean or lazy; 'tis open source scallywags bein' efficient. Of course, 'tis efficient fer themselves, not fer th' person askin' a question. And why should they be efficient fer th' person askin' when they dern't know that person at all, answerin' that person th' long way could be a waste o' time, an' doin' so doesn't get them anythin' besides a warm an' fuzzy feelin' an' bein' late fer dinner?

That's why th' most important form o' documentation, trainin' documentation, is so commonly missin' from software, Open Source or otherwise. The best way t' get it is either takin' th' time t' experiment personally an' acquire it yourself, t' ask really nicely an' hope ye find someone with spare time on their hands t' give th' long answer, or t' make it worth someone's while t' give ye th' long answer.

That's called books, avast. I have a copy on order, as much t' support th' authors fer takin' th' time t' write trainin' documentation as because I need it meself (although I've no doubt I'll learn somethin' from it meself).




Nice analysis o' th' situation. I'm new t' Drupal an' have made th' commitment t' climb th' curve. Do ye think some sort o' Wikipedia-style documentation might work? The current Handbook system seems a little clunky.



Think a page is missin' from th' current documentation?
Create Content> Book page

Think a page needs an update?
Scroll t' th' bottom an' click Add Comment, we'll keel-haul ye! Oho! For extra credit, file a doc issue an' get yer comment incorporated quicker.

It's really not that hard.

What skor said

The Drupal handbooks be already, IMO, better than a wiki. They're reasonably publicly editable, but ye get th' advantage o' a real hierarchy o' information rather than th' disorganized blob o' a wiki. You also dern't need t' learn yet another obscure proprietary language.

The main difference is that global-edit powers be restricted t' a smaller number o' scallywags; That's a good thin', because technical docs generally do have a clear "right" an' "wrong" answer t' many subjects, an' ye dern't want any random user able t' edit, say, th' "What Drupal is good fer" or th' Drupal history page.