I hate Drupal's documentation. There I said it. Go ahead and flame me. I don't care. It's the truth. I recently came up against this lack of documentation issue when I decided to use JQuery UI Accordion on my comments.

I found the documentation for comments in multiple places, but nothing really spelled out how everything worked, not even my wonderful assortment of Packt Publishing Books. I finally ended up opening the Comments module folder and reading the comment.tpl.php file. The example code got me on the right track quicker than reading the API and theming documentation had. And I soon had my output rendering properly except for one, pesky little thing.

There was a seemingly random <a href=”....$comment->cid”></a> somewhere in either my template or the core that I couldn't find. I googled, I pleaded for help on the forums, and I emailed friends searching for this irritating piece of code. My efforts rendered blank looks, numerous complaints on theming comments, a few theming examples, and silence.

Disgusted, I read both my template and my subtemplate files. Then I ran an advanced search on the entire Drupal core, and I found it tucked away inside the comment module itself. (See the comment.module file.)

$output .= "<a id=\"comment-$comment->cid\"></a>\n";

It was probably the six hours spent digging for an answer that incensed me beyond all reason and made me do something that I normally scream you should never do. I edited the core.

I took my delete button and deleted this bit of nastiness so quickly it would make your head spin. Why because this extra element that was being inserted above my individual comment code and consistently blew up the accordion I was trying to use.

By the way, this reference was already being used within my custom comments template. I've since decided it was unnecessary for my site and removed it.

Then I did something really stupid. I posted on the forums under my own question and said I'd found the problem and I'd deleted it. Perhaps, I should've added “in a fit of pique” to that statement, but I don't think it would've made a difference.

There was a little bit of back and forth, and I mentioned that once I had the fix for my issue documented I would make it available to the community.

That's when I got the comment below.

“Comment module has many theme-able functions, if you understand how to use those you understand how to do what you want without hacking core, so theres really no need for us to have screeds of info about doing this or that simple adjustment, just copy/paste the theme function and you're away.”

Forgive me, but I believe the point of this entire post (and the key issue) was that there wasn't adequate documentation. Please repeat after me, if you have to read the code to find the hooks, functions, etc., there isn't adequate documentation.

Documentation is supposed to document what a given function does without you having to read the code. That's why it's called documentation. Perhaps, four plus years dealing with WordPress has spoiled me, but I don't think that's the problem.

This is good comment documentation.

This is what I finally found by going to Theming Guide > Drupal 6 Theming Guide > Anatomy of a Drupal 6 Theme (if only all of the documentation looked like this page) > template files > comment.tpl.php. No where in any of this documentation (nor in the module documentation) does it mention that the module (not the module template, the module) inserts html into your final output. In all fairness, WordPress doesn't mention this either.

If you look at the documentation, you'll notice that the only difference in the comment documentation is that the WordPress docs have an example with the documentation and all of the form theming documentation is grouped under one topic, meaning you don't have to search for it across different sections. (No jumping from the theming docs to the API docs.)

Not having cohesive documentation is a major barrier for newbies. Not everyone wants to read the core code to write a theme. And quite honestly, I don't think anyone should have to.

What disturbed me more than anything was the implication that there's somehow no need to document the “simple adjustments”. Now, I've run across some snobs within the Drupal community and I've also run across some wonderful people. But the idea that you don't want to document how a core piece of your software functions sufficiently to adjust it without reading the module itself disturbs me.

While I don't think this one opinion is representative of the community as a whole, this isn't the first time I've seen an attitude towards documentation like this within Drupal. After my 4.5 failure, I watched the community's attitude towards documentation improve for several years before I downloaded Drupal and tried it a second time. (That's when I fell in love with the software, not the docs.)

In my opinion, an open source project is only as viable as its community. And it's community is only as viable as it is welcoming. Welcoming means documenting the little stuff, having some advanced users do a little hand holding in the forums, and having users who act as advocates. (Drupal has improved in leaps and bounds, I'm not meaning to imply that it hasn't.)

This also implies a degree of civility (and the exchange between myself and the other user was civil) and a willingness to drop the technical lingo with a newbie, which takes effort and practice. I try, but I don't always succeed.

Perhaps my hatred of the docs, which strike me as jumbled and disorganized most of the time, is unfounded. Then again, if I had this reaction to them, there's a chance someone else either has or will.

I like the flexibility Drupal gives me. A few questionable forum posts, poor documentation, and Ubercart's paypal integration, which was sending multiple emails until I became aware of the problem, won't run me off. I have too much time invested in it, and there isn't anything else on the market that will do everything I need this site to eventually do that uses PHP, SQL, and is within my price range.

Plus I like tinkering with it in my localhost (and in brave moments, live). I'm adventurous and I enjoy coding. I've enjoyed coding ever since I did my first website back in the 9th grade.

But my background is more diverse than just coding. Working in knowledge management and teaching has given me a very different perspective on some things. Drupal is a great project. Users like Lulabot make it even greater by their willingness to help educate the community. But documentation that you have to print out, highlight, cut apart with scissors and tape back together to make it make sense harms the project. If separating API documentation from everything else makes it difficult to use the documentation, combine the two. If it's difficult to sift through it and determine what applies to Drupal 5, 6, and 7, create entirely separate documentation for each version. Repeat some sections if you have to.

As for documenting how I created my accordions, I will write it up, and I will submit it to the Drupal theming documentation as a recipe. I have a few things to finish up, including moving the hacked core to the template.php file first before I submit it, but one person's comment won't stop me from doing it.

That's all the rant that I have for today. As for why I posted this here, instead of to the forums...it's my blog. It's fine to rant on occasion within my own space. It's not appropriate to do so in the forums. (Well, if the post's name is Rant Here, it might be okay.)

As for the issues I perceive with the documentation, I may or may not submit them as documentation bugs/feature requests, depending on what they are. I need a cooler head before I make any decisions on that one.

(By the way, I get more use out of this cheat sheet than I do out of the Drupal API Docs.)