A Rant : Why I hate Drupal’s Documentation

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 Drupal’s 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 inserted above my personal comment code 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 Drupal.org forums under my 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 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 there’s 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. Period.

Drupal prides itself on being “developer friendly”, but sometimes that “friendly” attitude shots them in the butt.

Documentation should 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 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 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.)

Related Posts:

• No Related Posts

Confessions of a Yarnaholic

By Me

Edited and Commented by kcknits (aka My True Self)

Hello, I am a yarnaholic. Fiber of all types invades my home; its siren call renders me powerless. Strike this sentence! This is not an invasion. It is a willing collusion resulting from the symbiotic relationship between man and sheep. I am an equal opportunity yarnaholic–acrylic has as much of a chance with me as cashmere. Equal opportunity my foot. Cashmere and bison are expensive. I’ve even bought fun fur because it was well…"fun". The swatch looked cute, but the finished scarf must never see the light of day. Remnants–those innocuous little half, quarter, and eighth balls–have sentimental value and must be pried from my dead fingers. The acrylic may be used for tying up plants, but touch my wool at your own risk!

I confess I give the fruits of my labors to others to justify my yarn habit. But I did keep one pair of socks, a scarf, a hat, two pairs of mitts, and the hideous fun fur for myself. My addiction harms my loved ones, forcing them to graciously accept clown socks and sweaters two sizes too large. My aunt asked for the purple, green, and orange socks. She even picked out the yarn. There’s no accounting for taste. As for my best friend, she crash dieted while I was knitting. Besides, the sweater fits now. Even my dog has suffered because of my affliction. The snow booties, hat, and sweater looked so cute on her. Alas, malinois aren’t poodles and she meticulously tore the hat to shreds. She’s now on my “Do Not Knit” list.

I go to craft fairs and stand in the alpaca booth for hours trying to decide between the cream and brown lace weight baby alpaca before going home with both. Leaving them both there would have been a crime of immeasurable magnitude, particularly when they gave me a Sunday afternoon discount.

When I moved, I discovered I owned five things: books, knitting books, yarn, knitting needles, and CDs. Imagine how heavy the book boxes would have been if I hadn’t filled them halfway with yarn. I gave away my movie collection for yarn space. My favorites are all available online and I needed the space. Instead of china, my sideboard houses yarn, carefully preserved in hermetically sealed bags. Fancy plates that I will never use are useless. I even purchased a vacuum sealer to support my habit. In your face, moths!

At tax time, I go through my receipts and calculate how much I spent on my hobby. Appalled by my yearly yarn expenditure, I lie to myself and claim I spent less than I actually did. I rationalize this by saying I am overpaying my taxes, which supports my government. This always sounds better than saying what percentage of my income I spent on yarn. Oddly, I’m okay with this practice.

Before I purchase yarn, I spend inordinate amounts of time studying the different brands. I will even PM people on Ravelry and ask about wear. In short, I am obsessed. This is not obsession; it’s research. Hand knit socks should last for many years and this is the only way to know.

My New Year’s resolution was to only knit from my stash. I kept it for five months before asking for yarn for my birthday. Well, everyone asked what I wanted. It’s not my fault yarn was cheaper than the new computer I need. I have a problem. No, I don’t.

With my assistance, smooshy balls have invaded my home. They are like gremlins except they replicate without water. I wish they were like gremlins. Then I would have enough of that yummy Madelintosh for two pairs of socks. Before I drown in my self-made vat of fiber goodness, And I would want to stop this from happening why? I am turning myself over to a higher Power and begging for help. Only through His grace can I overcome my addiction and clean out my yarn basket. He asked for a sweater.

Related Posts:

• No Related Posts