First Video Tutorial

Well, it’s not exactly my best work, and my accent is a little too obvious for my taste, but I’ve finished my very first video tutorial. It’s a crochet provision, nothing fancy.

I’m inordinately proud of myself. After struggling with this for over a month, I finally have something that is good enough (not perfect, but it’s better than my previous attempts) to show.

Related Posts:

• No Related Posts

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

On Publishing, New Year’s, and Family

New Year’s isn’t a day that I normally use to stop and take a breath. I typically spend the day planning out my strategy for the next six months, reviewing accounts, and such. In essence, it’s just one of many days that I spend working.

This year is different. The past month has been both busy and fruitful, but mostly busy. After several years of beating on the doors and getting enough rejection letters that they’d probably be hip deep if I printed them all out, three of my poems were accepted and published in the latest Fib Review. (I’m actually more excited about these than I am about anything else I’ve done in the past year. Sad, isn’t it?)

I also had a completely random moment, wrote a little tweet about a father telling his son a blinking red light was Rudolph, sent it in to Thaumatrope because their tweets seriously make my day, and had that published too. The inspiration for this one was my father who used to tell us that the light at the radio tower was Rudolph. I was seven before I noticed that the light was there year round, but even then it never failed to send both of us running for our beds. (And some of you are probably wishing I’d posted this little tip before Christmas…)

I finished the deadline knitting. And for the record, loosing your chart, having to recreate it from the sample, and then screwing up badly enough to have to rip the whole thing out after you’ve finished 2/3rds of it, isn’t fun. It’s done. It’s gorgeous, in my not so un-biased opinion, but it’s a miracle I still have any hair left.

Then my father got a cold and promptly gave it to everyone in the family as a Christmas gift. I got sick two days before Christmas and I’m still not over it. It was bad enough to interfere with my last minute knitting, which means his Christmas gift is still in my basket.

I’m still busy with secret projects and the Newsletter, which will launch on January 5. The Newsletter is a new step for me, but I think it will be a good one. It features a monthly drawing, and I’m experimenting with a Ravelry notebook ad to build interest. If anyone wants to mention this month’s drawing ($25 WEBS gift card) on your blog or tweet it, let me know. I’ll be happy to reciprocate. If you’ve already signed up for the newsletter, you are automatically entered in the drawing.

Here’s hoping this year’s better than last!

Kristle

Related Posts:

• No Related Posts