Drupal Documentation
Responding to this item in KairosNews wherein it is argued, regarding documentation problems, that users should "revise the existing documentation or provide new text as needed and negotiate with the project to have your changes included."
The problem is not that the help documents do not exist, mostly.
The problem is
(a) that the Drupal website is very badly organized, and
(b) searches for Drupal help are generally futile, and
(c) help that is located is often obsolete or wrong
In other words, the solution is out of our hands. We do not control, and cannot change, the Drupal website. And therefore we cannot fix the documentation problem.
I documented many of the specific instances in my 13-part series on installing Drupal last year (that it took 13 parts is an indication of the problems I was facing - yes, I was trying to do a lot of non-standard stuff - but the point is that it gave me a very clear view of the problem).
The problem is, to be more specific:
(b) searches for help on the Drupal site typically result in lists of meaningless and useless discussion pages, rather than anything like documentation, and
(a) even when you land on a page that might be useful, such as a module distribution page, help is not available from that page
(c) and when you actually find some help, it frequently refers to a module that is now obsolete or process that no longer exists
I don't know why, but search engines are utterly unable to distinguish between what is important on the Drupal website and what is utterly trivial. Hence, a search for something specific displays a long list of meaningless chatter, rather than a help page.
They are not helped at all by the Drupal website. Consider, for example, the help page at http://drupal.org/node/363 (this was chosen at random; it is completely typical). Note first that the URL offers us no help. The page title is "Basic site configuration | drupal.org" (everything is 'drupal.org').
On the page, terminology is inconsistent and vague. For example, "You will want to start your configuration with your drupal site's basic settings can be found on the settings page, which you can reach by clicking administer » settings in the navigation block." Clicking the link does not take you to 'basic settings' but rather 'Settings'. This page contains another link to 'General Settings' (note that you still haven't found anything) and very advanced topics, such as 'clean URLs' (where you are helpfully told "this works only for Apache servers which have the LoadModule rewrite_module configured and mod_rewrite enabled in httpd.conf configuration file" (no links).
On the 'General Settings' page ( http://drupal.org/node/43794 ) we are told how to set the site name, email address, slogan, etc. But nowhere on this page are we told that these options are reached by clicking on by clicking administer » settings. If we were searching for a way to change the slogan, even if we landed on this page, we would be completely stymied (in fact, of course, the search result for 'slogan' http://drupal.org/search/node/slogan does not take us anywhere near this page).
Now it's all very easy to say that people should fix this. But there is a lot more to simply writing some decent documentation needed to solve these problems. Specifically:
(a) The Drupal website needs to be split from the Drupal developer community website and the Drupal user community website. It is just a bad idea to mix up discussion threads with documentation, especially when the volume of discussion dwarfs that of the documentation.
(b) Drupal elements (such as, say, the 'Administration Menu') should be named, and this name used in both titles of documentation pages and links to those pages.
(c) Help pages on the Drupal.org should be rewritten to provide help on the specific topic. Boilerplate links to generic pages (something very common in the module documentation) should be avoided. Links that confuse (such as 'There are many other places to configure Drupal.') should be avoided. Self-congratulation ("A lot of the information you are asked to supply on the settings page is self-explanatory") should be eliminated.
(d) Drupal's internal search should be altered to give priority to certain types of documents (such as help pages) - despite the software design, not all nodes are equal.
(e) Documentation for different versions of Drupal should be on different websites or should be very clearly marked as such (colour-coding documentation for each version would be a good idea).
(f) Modules should be required to pass compatability tests before being included in Drupal's documentation or search results. Documentation and code for modules that have been abandoned or obsoleted should be removed from the site.
(g) Other solutions, which I may not have thought of.
Now - importantly - a typical open source user can't just walk in and make changes like this.
Even if they created perfect documentation, it would not appear on Drupal's website unless the website was radically redesigned, which is not likely to be done at the request of a typical user.
And even then, splitting the site apart, changing the search code, etc., are well beyond any sort of fixes the average user can provide.
The fact is, the people at the top (or the core, or the heart, or whatever) of the Drupal project will have to address this. Nobody else has the influence or expertise to do so, and very few people have the years of dedicated service it would take to attain such experience and influence. That's just a fact.
The problems with Drupal documentation are systemic, and because very little attention has been paid to the issues that have been widely cited, the problems persist. people - even people who devote the bulk of their time to open source - are not willing to pursue solutions in this light.
The problem is not that the help documents do not exist, mostly.
The problem is
(a) that the Drupal website is very badly organized, and
(b) searches for Drupal help are generally futile, and
(c) help that is located is often obsolete or wrong
In other words, the solution is out of our hands. We do not control, and cannot change, the Drupal website. And therefore we cannot fix the documentation problem.
I documented many of the specific instances in my 13-part series on installing Drupal last year (that it took 13 parts is an indication of the problems I was facing - yes, I was trying to do a lot of non-standard stuff - but the point is that it gave me a very clear view of the problem).
The problem is, to be more specific:
(b) searches for help on the Drupal site typically result in lists of meaningless and useless discussion pages, rather than anything like documentation, and
(a) even when you land on a page that might be useful, such as a module distribution page, help is not available from that page
(c) and when you actually find some help, it frequently refers to a module that is now obsolete or process that no longer exists
I don't know why, but search engines are utterly unable to distinguish between what is important on the Drupal website and what is utterly trivial. Hence, a search for something specific displays a long list of meaningless chatter, rather than a help page.
They are not helped at all by the Drupal website. Consider, for example, the help page at http://drupal.org/node/363 (this was chosen at random; it is completely typical). Note first that the URL offers us no help. The page title is "Basic site configuration | drupal.org" (everything is 'drupal.org').
On the page, terminology is inconsistent and vague. For example, "You will want to start your configuration with your drupal site's basic settings can be found on the settings page, which you can reach by clicking administer » settings in the navigation block." Clicking the link does not take you to 'basic settings' but rather 'Settings'. This page contains another link to 'General Settings' (note that you still haven't found anything) and very advanced topics, such as 'clean URLs' (where you are helpfully told "this works only for Apache servers which have the LoadModule rewrite_module configured and mod_rewrite enabled in httpd.conf configuration file" (no links).
On the 'General Settings' page ( http://drupal.org/node/43794 ) we are told how to set the site name, email address, slogan, etc. But nowhere on this page are we told that these options are reached by clicking on by clicking administer » settings. If we were searching for a way to change the slogan, even if we landed on this page, we would be completely stymied (in fact, of course, the search result for 'slogan' http://drupal.org/search/node/slogan does not take us anywhere near this page).
Now it's all very easy to say that people should fix this. But there is a lot more to simply writing some decent documentation needed to solve these problems. Specifically:
(a) The Drupal website needs to be split from the Drupal developer community website and the Drupal user community website. It is just a bad idea to mix up discussion threads with documentation, especially when the volume of discussion dwarfs that of the documentation.
(b) Drupal elements (such as, say, the 'Administration Menu') should be named, and this name used in both titles of documentation pages and links to those pages.
(c) Help pages on the Drupal.org should be rewritten to provide help on the specific topic. Boilerplate links to generic pages (something very common in the module documentation) should be avoided. Links that confuse (such as 'There are many other places to configure Drupal.') should be avoided. Self-congratulation ("A lot of the information you are asked to supply on the settings page is self-explanatory") should be eliminated.
(d) Drupal's internal search should be altered to give priority to certain types of documents (such as help pages) - despite the software design, not all nodes are equal.
(e) Documentation for different versions of Drupal should be on different websites or should be very clearly marked as such (colour-coding documentation for each version would be a good idea).
(f) Modules should be required to pass compatability tests before being included in Drupal's documentation or search results. Documentation and code for modules that have been abandoned or obsoleted should be removed from the site.
(g) Other solutions, which I may not have thought of.
Now - importantly - a typical open source user can't just walk in and make changes like this.
Even if they created perfect documentation, it would not appear on Drupal's website unless the website was radically redesigned, which is not likely to be done at the request of a typical user.
And even then, splitting the site apart, changing the search code, etc., are well beyond any sort of fixes the average user can provide.
The fact is, the people at the top (or the core, or the heart, or whatever) of the Drupal project will have to address this. Nobody else has the influence or expertise to do so, and very few people have the years of dedicated service it would take to attain such experience and influence. That's just a fact.
The problems with Drupal documentation are systemic, and because very little attention has been paid to the issues that have been widely cited, the problems persist. people - even people who devote the bulk of their time to open source - are not willing to pursue solutions in this light.
yes! documentation, especially for non-hardcore-drupal-geeks is really spotty.
ReplyDeleteI completely agree. I'm learning Drupal at the moment, and find most of the documentation impenetrable.
ReplyDeleteI am finding trial and error to be the best way to learn, which is not particularly efficient. Questions asked on the forum often go unanswered, or are answered (despite my stating that I am new to Drupal) in a manner as unintelligible to a new user as the Handbook.
I'm at the stage where I know that Drupal is an excellent CMS, and I have chosen the right one, but it's taken a long time to get even that far!
Thanks for writing about Drupal on your blog - I've learned quite a bit from you.
useless.
ReplyDelete"I wrote on my own personal blog." Unless you get involved with the community you are merely standing on a street corner wrapped in your own little world.
It is like the person standing outside a building on fire says 'oh, theres a fire, someone should do something about it' and then goes home without calling the fire department or trying to wake people up.
It's nice that you think you know something, but if you can't get involved then all you are doing is nothing.
Except I did do something about it - I pulled the fire alarm.
ReplyDeleteYou are complaining because I didn't put on equipment and put out the fire.
Sorry, but I am needed elsewhere.
Not everybody can work on Drupal. Not even everybody who supports open source.
I spent a lot of time learning Drupal, working with it extensively, and documenting the problems.
If you think that's not enough, well, that's your problem.