Log in

No account? Create an account

Previous Entry | Next Entry

I'm Stuck with a Valuable Friend

I have to apologize. I have been abusing my f-list. It seems that I have no time for anything other than angry little foments and quips.

But I came across a quote today that explains why more succinctly than I can. It's from the Google Drupal 7 Usability Study 2011. It states:
Building a Drupal website for the first time is like playing connect the dots. But some dots are invisible, most are not numbered, and you have no idea how many dots there are.

They took eight of those technical wünderkindern that populate the halls of Mountain View. People you would expect would have no problem adapting to a new CMS. They sat them down and said. OK, you want to make a website. Here's Drupal. Show us what you're thinking...

And the results were sad. And at not time did they crack the hood and actually try to look at using the API. No, seriously. And if the interface is confusing and intimidating, Trust Me. The API is a dozen times worse. And Drupal's decision to rewrite itself every major iteration means that any existing documentation must explicitly say what version it's for. Or else it may not apply. Actually, will likely not apply AND waste hours of your time if you try it.

I can't tell you how many pages of "here's how you implement a theme_widget_alter_memory_after_registery_building_wahoony_registery_alter() function" that don't explain WHY you should want to do so or WHERE you would implement it. What documentation HAS been written out is so grammatically unsound that it leaves you puzzling what it is trying to say.

You literally have to open up all the code and poke through it as if translating some arcane Rosetta Stone by loading your site in a browser window while looking at the error log and the database log in order to understand what it's doing. Or you can download other modules and see how people "in the know" do it. And discover that there is not that much shared technique between them.

The real problem I'm facing is that at any point in the process of solving a "problem/task/feature", there are a half-dozen possible ways of proceeding to the next step. And every step is another exhausting search for the following step, weighing the relative merits of alternate options.

I'm beginning to think that the core Drupal development team has suffered a kind of schism from their user-base. As if they have become so specialized and so distant from the land of clear explanations that they are no longer capable of doing so.

And I know why. I've been there, writing that kind of documentation. It's a psychological state you get into when you really understand your code.

Thankfully a smattering of real, thought-through technical books has started to trickle out. If my current project hadn't been delayed, I'd still be trying to do this with NO sane documentation at all. Only the incomprehensible, out-of-date, and machine generated api guides (here's an example of how NOT to write an API guide) a handful of video demos put up by an eccentric Swedish non-tech developer full of lines like "oops--why did it do that. No, let me try this. No. Well, if it worked the way it should have, you would see this. No, not this. Well, it would be different. I guess it's a bug".