This Is Why Official Drupal Documentation SUCKS

From my upcoming site's blog (I've already started a site blog even though I don't anticipate promoting the site until December!):

I've been struggling with Drupal for half a month now, and though most of what had originally bedeviled me has since been resolved, new puzzles still crop up so prodigiously that I wonder whether I shouldn't just hire someone to do it all for me.

But I abide in my suspicion that Drupal is not really hard to learn or use. Not inevitably so, anyway. After all, David Mercer's book has helped me to build a really decent website with Drupal in just a week. However, I believe my "zero-to-sixty" was also due in great part to Drupal itself. No, Drupal is not hard inherently. It's just that there isn't an actual manual for it yet.

Luckily, a handful of books are on the horizon, looking to improve this unhappy state of affairs. Here's what I'm looking forward to:

Practical Drupal: Evaluating and Using a Web Content Management System by Niall Mansfield ~ I'll be very interested in comparing this title against the Mercer book, as they have almost identical objectives. It's supposed to be out by now but Amazon still has it in pre-order status.

Leveraging Drupal: Getting Your Site Done Right by Victor Kane ~ Of particular excitement is the emphasis on customization and creating "non-Drupal" looking sites" (ahem, ahem!). Due late January.

Using Drupal by Angela Byron, Addison Berry, Nate Haug, and Jeff Eaton ~ Written by many of the talking heads in the video Understanding Drupal, this should be one helluva "cookbook," given all the "celebrity chefs" involved! It aims to address two issues that make Drupal appear so hard: the lack of step-by-baby-step hand-holding necessary for newbies, and the lack of properly comprehensive documentation for the over 500 modules available to use. This may well turn out to be the legendary missing manual that everyone's been looking for! Due mid-December.

Cracking Drupal: A Drop in the Bucket by Greg Knaddison ~ Now this is an extremely interesting title, though likely for more advanced users: it's all about trying to break Drupal and hacking into a Drupal site. Hmmm!! Due late February.

Drupal has got this strange Wizard of Oz quality to it, where there's all these intimidating flashes and booms but behind it all is just a nice little piece of software that's really quite an agreeable fellow. Here's hoping these volumes prove to be the clasp that pulls back the curtain!

the solution is much much simpler than pulling in a student to write a thesis..all it requires is smarter community management and a better understanding of how to harness collective intelligence.

Drupal really needs a village square. One port of call for all members of the Drupal community.

I know a lot of drupal veterans who rarely visit drupal.org anymore, unless they are stuck and are searching for something . They prefer to hang out elsewhere, such as on the many Drupal irc channels that are out there.

The impact of that is that the drupal.org's forums are mostly populated by newbies, all asking each other the same questions that have been asked numerous times already. Which is even more off-putting for veterans and the cycle continues.

It's getting so bad, if a newbie happens to stumble into the drupal development irc channel and asks a newbie question they are usually told, in no uncertain terms, to bugger off to a different irc channel. Off that newbie goes to an irc channel, that is full of.....you guessed it, newbies, all asking each other the same questions that have been asked numerous times already.

That lack of vision with how to harness collective inteligence and the spreading out of the community to various corners of the web means that there is an enormous amount of wasted intelligence and a lot of replication. joe developer doesn't know what jim developer is doing.

As far as wasted intelligence is concerned, how hard can it be to place a button at the bottom of forum threads called SOLVED or CONVERT TO HANDBOOK PAGE....so the Drupal search doesn't drag up redundant threads and a visitor, who asks a question and is answered with a solution, can also click on a CONVERT TO HANDBOOK PAGE option where their solution flows into the handbook and all the visitor has to do is tidy up the text, categorise the page correctly and click on submit.

9 times out of 10..a visitor who gets an answer that solves a problem or provides a solution for what they wanted to do are really chuffed that they've got an answer and I think they wouldn't mind spending an extra few minutes logging that intelligence into the handbook.

At the moment, there is no 'call to action' when a thread on the forum is 'complete'. Which means the search results on drupal.org are full of multiple threads dealing with the same questions....a classic example of wasted intelligence.

Are there not "formal channels" in place for would-be developers to network with one another, so that communal brain-power is concentrated and not so dispersed?

Not really. A lot of developers avoid these forums, for the reasons pointed out earlier, but, there is an irc channel for Drupal developers, another seperate one for themers and another seperate one for support...there's probably more...I've lost track.

I know that IRC channels freak out some IT admins in companies, because of firewall issues and security worries, so some can't use the IRC channels as much as others.

In my opinion, Drupal really needs a village square. One port of call for all members of the Drupal community. Which doesn't mean themers will start leaping into discussions with developers or newbies will jump into developer discussions...it just means that everyone knows roughly what's going on in other areas.

As an example, fitness trainer, the group of people who can make a difference with the drupal documentation will probably never read your thread and your ideas. Which is a pity. That's not because they're not interested. It's because they don't hang around here that much. Which is a shame.

Like I said earlier, drupal is undergoing a redesign at the moment and hopefully the new design will address a lot of the shortcomings I'm rambling on about and improve comunity management and harnessing collective intelligence.

That's what community plumbing really is. It's not just slapping a forum up and hoping for the best.

I did notice that there were modules which concerned the same general subject area, like the core forum module and the Advanced Forum module, but figured on them being a case of "basic" functionality and "advanced," and did not think of them as being duplicate efforts of the left hand not knowing what the right hand is doing sort....

I don't know why you would think that. I know perfectly well what the forum module does. Advanced Forum is an extension of it, not a duplication.

Michelle

--------------------------------------
See my Drupal articles and tutorials or come check out life in the Coulee Region.

Welcome aboard. I'll try to get the site up to snuff in the next week, and write a contributor's guide.

I thought some more about your ideas. Instead of the treeview/flowchart model, I'm thinking of filtering out the available pages. For example, if someone has Windoze on a localhost, they wouldn't even see instructions relating to Linux & ISP's (except those relating to migration). Their instructions are also tailored according to their module list & Drupal version.

So I see the UI being like this: Anonymous users get generic info, or they can browse the jillions of instructions with a TOC. Authenticated users get a screen asking about their configuration, then they are asked "What would you like to accomplish", then they get tailored instructions. Possible responses would be general tasks (embed images, start a blog, etc.), as well as more specific instructions for modules, etc. They can leave comments, and create multiple configurations for their ISP and local setups. Users are eventually promoted to contributor & editor roles.

I'm thinking about Linux installers that know which programs conflict w/ each other. Troubleshooting capability could be added with a knowledge base, narrowing the possible causes/cures depending on what's configured. Added structuring of the issue lists at drupal.org would allow us to tap into them directly.

Individual instructions would be DB entries, aggregated into custom instruction lists.

But I'm dreaming. This isn't going to exist soon, but the contents of the book I've started could eventually be pasted into an app like this. It would be a good idea to check the module list, as well as projects like Moodle, to see if something similar already exists.

Honestly, Drupal documentation SUCKS big time.

But far from being disheartening, it should, eventually if not immediately, prove to be the catalyst that redoubles your efforts into more meaningful accomplishments!

You wouldn't know what you're doing wrong unless someone tells you...and sometimes it takes a big fat HEEELLLLOOOO!!!!! rather than a timid "excusez moi s'il vous-plaît"....

I'm sorry I come across as being entirely unreasonable. But realize that all progress depends on unreasonable men. (George Bernard Shaw there for ye.) Change never comes from the polite and agreeable. Never. Your eight-hour workday, your paid sick leave, your health benefits, universal suffrage...nothing has ever come from being reasonable, from asking, from hoping. Is it "reasonable" to ask your employer to pay you when you're sick? Is that his or her fault? Why should your decision to have a baby mean paid maternity (and even paternity) leave -- in some cases involving whole years??

Nothing is reasonable or unreasonable as such. Ask whether it is useful or not.

Drupal documentation sucks because it hasn't helped many newbies learn Drupal. And by "newbies" I mean someone with no programming experience, etc. But me and Dave and some others will be cleaning it up -- as he finds the time, and as I learn more and more.

I'll be helping out on this official site, too...you won't see much of me around these forums soon enough, I can guarantee you that.

But don't take things personally. Drupal documentation just hasn't helped that many newbies. Don't you think there's something wrong with that?

Instead of being self-satisfied in the manner of Western politicians congratulating themselves over "democracy" and "freedom," how about some honest dialog? Problems don't get solved until they're recognized in the first place.

I'm sorry to have to play the gadfly, but for something that's about to hit version 7, documentation is sorely lacking.

The Drupal Dojo has some good screencasts.

http://drupaldojo.net/lessons/

http://groups.drupal.org/drupal-dojo

Unfortunately you do need some knowledge to know what lesson you need to watch to tackle a problem.
The order of the Lessons isn't necessarily the best order for a Drupal beginner either. For instance I'd recommend viewing Lesson 1, skip the next 2, watch lesson 4, skip lesson 5 and finish with Lesson 6 to start with.

I think the problem is that you're looking at this backwards. You're looking at modules and expecting them to explain why you would want to use them. You need to first decide what you want to do with your site and then find modules that fit that need. If you don't need to list the nodes on your site then views isn't going to seem useful to you.

I stand by what I said. Yes the documentation could be better but it can only be dumbed down so far. No amount of documentation is going to replace common sense. If you can't fathom what a list is or why your site would need to have one then you need to educate yourself about websites in general before you're ready for modules' documentation. I know I'm certainly not going to explain what a forum is and why a person would need one on their site in the advanced forum documentation. I assume a basic knowledge in my documentation as do all maintainers.

Michelle

--------------------------------------
See my Drupal articles and tutorials or come check out life in the Coulee Region.

OK, if Michelle won't dumb it all down enough, I'll have a go... :-}

You do need a dictionary.

A list one thing after another. Usually text. Sometimes boxes.
Text is the technical word for lots of letters put together. Usually to make words.
Words are the things that people use to communicate. You'll find a lot of them on many websites.
Those words you see in the blue boxes over the right there, they are mostly lists of links.
The stories you see on the front page are lists of story previews.
When you search, you get lists of results.
Many menus are special types of lists.
OK, have you got an idea what lists are yet?

Now,
In the beginning, you get a list of all published nodes on your front page, ordered by date. That's OK, but some folk want more complicated lists to appear in other places.
Like "all forum posts by the boss".
"just the image previews from posts about flowers"
"an alphabetical table of article titles and their authors"
"most recent 5 comments by people from Australia"

These lists may be filtered.
*sigh* OK, A filter is something that lets some things go through and other unwanted things not go through.

Those are all basically lists of information, but what gets shown, how it gets displayed, in what order, and with which filters, are all parameters that can be chosen by defining a view. A view is a ruleset for these displays. The views module allows users to make up and mix together hundreds of these rules to get their customized results.

You get to set how many things in a list/view show up.
Whether they display a pager.
A pager is the device at the bottom of the page or block that shows "read more" or page counters
Whether you see a teaser or just a title.
Whether it displays the date or the author name.
Whether they come in blocks, tables, or down the page.
Whether they get attached to different content, whether different people see different stuff, and how each part of each part of each view is themed.

Why is it so impossible for you to see that :

• those hundreds of choices are not needed for everyone, and would be bloody confusing to begin with
• but also those hundreds of choices are fecking awesome for folk who understand their content and now want to make it work exactly like they want!

If you don't want those features or don't want to understand those features, then skip it, but your complaining about the existing docs is going nowhere if it's your own reading comprehension that's at fault.

"A summary view to list by taxonomy term, with link to nodes" - this is really much to hard for you to get any idea about? You call that an example of what is confusing about the help documents?

Summary : short version of a larger story. Also known as "teaser" on web publishing systems.
View: how things look or are presented. In this case how lists or collections of items are shown.
List: do we have to go over that again?
... so far we have a list of summaries ... I just can't actually rephrase that concept any simpler for you.
Ohh, now we actually have a long word. if you'd paid any attention to the documentation you hate so much, you'd have got the message that "taxonomy terms" are pretty much a formal way of saying the same as what simpler websites call "tags". Words used for classification. Labels. Keywords.
Like when I say "you are a moron" then "moron" is a term I'm using to classify you.
So our list will contain things that are tagged with a certain term
Are you following yet?
Link is complicated web-jargon for those special bits of text that make the browser (the window thing on your computer-TV) show a new page. So our list will contain parts you can click on ... and can you guess what will happen? it will go
to nodes. Right. Node is not a word that you'll hear much outside maths and design and information and networking and computers. However, building a website does have something to do with those fields... you may have to be prepared to (shock) learn a new concept. The word node has been described many times on Drupal.org. Possibly too many, but for now we will just let you imagine it means web page because lump of data doesn't help much.

"A summary view to list by taxonomy term, with link to nodes"
A display of a collection of short descriptions of articles all dealing with one topic, which when clicked will take you to the full story

If this is the level of your problem with reading the docs, I don't know what sort of language can be used to provide the beginners guide you are looking for. Note that the shorter version is ... shorter. And actually contains bonus information because it's using more accurate terminology.

The good news id that I actually enjoyed writing this troll-food ... because I constantly picture 'fitnesstrainer' as being "Bruicie" from GTA4. Yeah man! Yeaaah!!

.dan.
_{if you are asking a question you think should be documented, please provide a link to the handbook where you think the answer should be found.}
| http://www.coders.co.nz/ |

... to post individual topics for each of your questions. They are off topic for this post, which many people are tired of anyway, so your pleas for help here may go unnoticed.