capacity building

Just a little to the left please. Flip it around. Put that on top of this. Call it by a different name. It is the little changes, that seem trivial and small, that often end up being real headaches to make and support our clients in making. Do we really want to try to build capacity with clients by teaching them to adjust #weight in hook_form_alter?

The Drupal Theming System is pretty powerful and, when done right, can offer a good avenue for our clients and their staff to edit, modify, and change their own website content. Its a lot easier to modify HTML files than Drupal module files.

A good example of where this kind of process is needed is on the user registration page. There are a lot of little bits of language and ordering to change and add, but to do so in Drupal module code can get a little hairy. Observe our technique to abstract the user/register form into a flat template file (while maintaing most of the other good Drupal goodness).

Step One: Create a theme override in your module code for the user/register form that executes a _phptemplate_callback to use a separate template file.

Step Two: Expand the theme override function made in step one to remove the titles and descriptions Drupal provides for the form elements. We do this in the theme function (instead of in a hook_form_alter) to preserve the original field titles so they can be used as part of any error messages coming out of form validation.

Step Three: Create "rendered" versions of each of the form elements and set them as variables that can be passed to the template file.

Note: This can also be done with a generic foreach loop (similar to the one in step two) that renders each form element automatically.

Step Four: Create a template file in your site's theme directory to build the user/register form with the customized variables we defined in step three.

Note: This file needs to be the same name as specified in the _phptemplate_callback (example: user_registration_form.tpl.php).

The drupal magic here is that the user registration form is now uniquely customizable by anyone who can edit the theme template. This allows for customized "prompts" for each profile field element, without changing the site-wide field name in admin/user/profile, and it allows for customization of the username and email titles and descriptions.

This technique will need to be modified to support external modules that modify the user/register form like LoginToboggan. It also needs to take into account things like "required" fieldstates.

Earlier this week I spent an afternoon setting up and configuring WYSIWYG editing for a client’s website. Although at Chapter Three we are big fans of HTML Literacy, we realize that many users would feel more comfortable in a WYSIWYG environment. We did a little brainstorming and came up with some basic recommendations to make TinyMCE work better.

1.) Keep the Interface Simple - TinyMCE out of the box has all of its bells and whistles displayed which is in some ways cool - TinyMCE can do a lot. However, much like the selection at Old Country Buffet, sometimes too many options can be confusing and hard to narrow down. There is a temptation to leave options there that “may be useful”. Instead, we first started by disabling all of the options and then selectively enabling only the options we really needed. This ended up being just the bold, italics, underline, font size, and ordered list buttons. Keep it simple or you will end up showing your users something monstrous like:

Bad:

Good:

2.) Resizing Good, Path Bad - TinyMCE allows for textareas to be resizable and this is a wonderful feature. It gives users more space to work and is far less annoying than having to compose a page long post by scrolling through a four line tall textarea. The problem is that in order to enable this feature in TinyMCE you also need to turn on the “Path Display” option. This feature allows users to see their current depth and path in the HTML code and can be useful in some cases - including building HTML literacy, but in most cases its both cluttering and confusing. To remove it and keep the resizing option, we simply enabled them both and then used CSS to hide the information:

.mceStatusbarPathText { visibility: hidden; }

3.) HTML Literacy is Still a Good Thing - Even though the user is working in a WYSIWYG environment, allowing the user the ability to be exposed to and maybe even edit the HTML code can be a really good thing. TinyMCE allows for the creation of a “HTML” button that creates (in a separate window) a rendering of the textareas HTML content and allows the user to edit the code. Now, it is best to keep the interface simple, but helping to educate users about HTML can be a really good step to improved HTML literacy.

4.) Only Use TinyMCE When You Have To - The easiest way to simplify the way TinyMCE is used on your site is to only use it in cases where you really need WYSIWYG editing capabilities. This is, unfortunately, a little tricky to do in Drupal since the Drupal implementation of TinyMCE only allows the display of WYSIWYG editing on a per page basis instead of a per field basis. This is typically not a problem since most pages just have one textarea, but if you have a page (say the editing of a particular node) with multiple textareas, but only want TinyMCE on one or two of them, its sort of tricky how to do it.

One possible solution - that we ended up using - is to use a theme override for the TinyMCE theme to enable or disable textareas based on name. This solution works in tandem with the built in display controls and simply adds the finer grain control needed. In this example, we have only enabled TinyMCE to show on node/* pages but have four different textfields that we do not want TinyMCE to show on. To accomplish this we use the following theme override:

Documentary films, when successful, offer the viewer an intimate glimpse into a situation as it unfolds. There is often a progression or growth that occurs through the film, as every mistake and every twist and turn is captured candidly. It’s captivating because it tells a story “as it happens” instead of recounting or remembering a story after it has happened.

So why should software documentation be any different?!

Imagine a film documentary where the director didn’t really think anybody was going to watch it, so they half-ass the editing process or just decide to skip filming some days. The end product would be a pretty incomplete documentary. Sound familiar?

The analogy may sound silly, and I doubt any software documentation will be as interesting as a well-made documentary film, but why is most software documentation so BAD? We’ve all encountered confusing, vague, incomplete documentation and the reason is most likely because people regard documentation as an afterthought. It is often minimalistic and leaves out many details that the general reader needs - more a footnote for the original author than for anybody else.

This makes for really boring or confusing documentation. Since the author is documenting something they have just finished, the information is not thorough or particularly valuable. They (developers and users) want to know what the author was thinking when they wrote it, why they wrote it, pitfalls, and would like to understand the author’s experience in a compact form. This means not glossing over details, and it also means not providing unrelated or distracting information.

It may seem like a daunting process to document software, and that is probably because:

a) Developers are allergic to writing.
b) Developers enjoy being as cryptic as possible (d0cum3nt4t!0n i5 14m3, d00d!!!)
c) People try to document things after they happen, which feels like a lot of work.

While I’m sure a) and b) have something to do with it, people more likely write bad documentation because they try and do it after they are finished. Nooo! It’s like taking a fascinating video documentary and summarizing the entire thing on a post-it-note. Somehow, not as thorough… ;)

It’s really easy to write good documentation, and the secret is to *document things as they happen* and not after they happen. If you notice something or realize something while you are working, just write it down somewhere, keep a running list, and most importantly: DON’T LEAVE ANYTHING OUT. Even if you think it’s obvious, it may not be obvious to the next person, and sometimes it’s not even obvious when you go back and read it yourself! Remember that you are documenting a process, so editing things out is NOT encouraged. Later on if you need to, you can go back and edit things that are extraneous or confusing.

The amazing thing about this process is that it FEELS like less work, because you aren’t forcing yourself to remember things. In some cases, it can help you plan out what you are working on, too.

You don’t have to be an expert on a subject to write good documentation. An expert tends to automatically make more assumptions, but newbies have a fresher perspective. Since most readers will be newbies themselves, they’ll be able to relate to the author’s tone and language as well. On the other hand, experts can explain things more thoroughly and concisely from a technical point of view. Both perspectives provide valuable insight on how something works.

Lastly, have fun with it! Throw in some jokes or drop a reference to P. Diddy once in a while. Reading this stuff can be agonizing so your readers will thank you for waking them up. ;)

As we’ve posted about before, the past year has seen almost 100% growth in the Drupal economy. Several great new companies and several good coders have emerged, and a new ethic of training and local groups has taken hold, and yet there just aren’t enough savvy web developers to meet the demand for Drupal-related services.

Like every professional services shop that plays heavily — our in our case works almost exclusively — in the wonderful world of Drupal, we’re feeling that talent shortage. And it occurs to me that poaching talent from our “co-opetition” and/or headhunting people with existing IT jobs — two popular ways to build out a development team — isn’t a long-term solution to this problem.

It Has Begun!

To that end, I’m excited to announce the formation of The Drupal Dojo, a community group dedicated to increasing the proficiency of apprentice and journeyman-level developers. The Dojo will work through the groups.drupal.org forums, and an IRC channel.

A middle-tier developer community is good for the project as a whole (#drupal intimidates a lot of people), and for enterprising individuals like myself, the idea of being able to build stronger relationships with up-and-coming developers makes obvious business sense. Seems like a classic win-win. I’ll be posting on group progress as it evolves.

I’ve arbitrarily said we need five learners and at least one other “expert” to start out. If you’d like to participate, subscribe now and help me get the ball rolling.

UPDATE:
Well that’s a surprise! 72 hours after creation we have 175 subscribers. The ratio of “master” to “apprentice” may be a bit off, but I think with the number of participants we’re bound to have some good results.

The other night after a little prodding from Drumm, I spent a couple hours reviewing patches for Drupal 5.0. My #drupal karma has been off for a while, and I needed a good excuse to start to get my hands dirty with the next version, so I’m glad he harassed me into helping out.

But man oh man, was I impressed when I installed 5.0 on my local sandbox. The “first impression” is simply worlds apart from the 4.x family of releases. It left me feeling really excited (wanting to contribute more), and inspired by this optimistic post by Gunner Langemark, I’m willing to hazard that 5.0 and 2007 could be a sort of Perfect Storm or Tipping Point for the project. Here’s why:

A Quantum-Leap in Usability
As Dries outlined earlier this year in Vancouver, Drupal is ahead of the pack in features and capability, but has been lagging in usability.

This usability gap is now being closed. While Drupal remains more complex, and thus has a longer learning curve, that curve is flattening. The improved “first impression” of a stock install, a revamped admin interface, and the addition of the jQuery library are some of the more obvious advances here, but a general shift in consciousness towards usability is yielding results across the board.

Some examples are in order. Check out these screenshots of 4.x’s stock “Bluemarine” theme:

Vs. 5.0’s default “Garland”:

Also, check out the difference in how the first admin screen is structured. Here’s the old 4.x version which displays confusing (and generally non-interesting) list of recent watchdog log items:

Vs. the 5.0 admin screen, which presents nice categories of tasks for administrators:

The cumulative impact of these usability changes will be huge in terms of growing the overall userbase and turning many more people on to the platform’s power. Bravo to the core team for making some strong choices in this regard!

Install Profiles = Drupal Products
Part of the new first-impression is the relative ease with which the default database structure loads. No longer does setting up Drupal require messing with phpMyAdmin or a command-line database session:

That’s a big step forward in and of itself, but there’s a lot more value in this system than just making it simpler to get a vanilla install up and running.

Drupal is special because it so well-engineered as a framework. It is stable, flexible, versatile and extensible. You can use it to emulate virtually any existing website. It just takes the right combination of contributed modules, configuration, a good theme, and a little planning.

If you’re good, this takes a couple of weeks at most. That’s huge potential power.

The presence of an install profile system crystalizes this potential. It gives experts like me a solid way to distribute our own site recipies — what we at Chapter Three like to call Drupal Products — so that they can be easily evaluated, utilized and improved upon by others.

The creating of a marketplace for Drupal Products will increase the pace of innovation while simultaneously lowering the barrier to entry for new and emerging players to get a taste of advanced Drupal functionality. It will drive quality, and open many higher-end/ambitious eyes to the value of building their website on Drupal’s open platform.

Professional Class Hits Critical Mass
I may be biased on this because I’ve just started a company and am doing pretty well, but it seems like the community of Drupal professionals (that is, people who make a living around the project) is continuing to grow at an incredible rate. The signs are everywhere:

There are now close to 1,000 self-identified Drupal service providers, and look at how CVS accounts and projects are spiking! Could it be that people are growing tired of the Ruby on Rails hype machine and turning an eye to big D?

The trends are good. I see more and more client-sponsored contributions, more and bigger Drupal-centric companies, more new faces in development chat, and every shop I know — including us — is desparate to bring on new talent. This all signals another year of robust growth for the Drupal economy: more jobs, more high quality work, more evangelism and training.

There’s nothing like being able to bring home the bacon to give something value and longevity. I think in 2007 we’ll see more innovative entrepreneurial groups spring up (somewhat like Lullabot did, more power to ‘em) as high-capacity professionals and new kids on the block alike turn on to what the Droop has to offer and decide to go pro.

The Perfect Storm
These three broad trends lead me to believe that behind the banner of 5.0, we could be on the brink of a “perfect storm” for Drupal in 2007, leading to a greatly increased public profile for the project both within the technology/open-source community and among the public at large:

• With gains in usability, the platform will shed much of its reputation as a “geeks-only” tool.
• With the proliferation of install profiles, the real muscle of the system will be available to less-expert users.
• More users and more power-users drive an explosion of new and better sites, and also bring new developers on board.
• A growing Drupal economy creates jobs for new developers and supports training activities — both formal teaching events and on-the-job apprenticeships — to build capacity.
• The proliferation of Drupal shops also means more targeted evangelism within industry verticals, more productization, and more high-quality sales and marketing efforts building buzz around the brand.

This all serves to pump more creative energy, talent, interest and paying development back into the core platform, driving further waves of growth and innovation. In real terms the sky’s the limit for now.

“Web 3.0?” Why stop there? Check out Garland’s ability to shift color schemes with a live preview:

Now that’s what I call cool.

The virtuous cycle of Drupal growth doesn’t seem to be headed for a breakdown any time soon, and the continued vibrance of the culture and community surrounding the project lead me to believe that these coming waves of growth (while sure to contain some turbulence) should be mostly positive and sustainable.

It’s a good time to Drupal!

Our methodology here at Chapter Three calls upon us to work ourselves out of a job. This is a shift from the olden-days of website professionals — call it the “Razorfish Model” — wherein a consultant or firm relied on strong design skills and a working knowledge of HTML to set up a client with something that looked slick, make a bundle on that, and then charge a high hourly rate to make content changes or additions.

Content Management Systems (CMSs) changed all that, first by allowing firms to build rough tools that could be used internally to drive down the cost of maintaining a site, then by granting this power to the client-administrator, and now to the client’s customers/community. This has changed the rules of how websites are run, and so much for the better. Since the advent of CMSs more of the potential of the internet as a democratic media has been reached, and more of the promise of “markets as conversations” has been realized. The trend is good.

One question that still remains is how clients enter content to their sites. Most of these folks are doing this for the first time (though if they’re successful online, not the last), and don’t have any real experience or understanding of how the whole system works. They’re unfamiliar with the concepts and syntax of HTML, generally having grown up on MS Word or some equivalent for text-editing.

In response to this there’s a temptation to deliver some kind of faux-“WYSIWYG” solution to provide a similar experience for editing content online. It seems like the right thing to do, and at first clients are excited and impressed that they have the power to format text at the touch of a button.

However, I put the prefix “faux” and those “scare-quotes” around “WYSIWIG” for a reason. The simple truth is that most implementations of javascript-based editors in complex content environments — e.g. more going on than a simple wordpress blog — create more frustration than they resolve, as clients quickly discover all the quirks and problems that come along with them. We of course still implement these tools (carefully, and in a limited way) for clients that want them — the customer is always right — but in the long run I think our objectives and those of our clients are better served by encouraging HTML-literacy.

One of our buzzwords around here is “Capacity Building.” By that we mean, essentially, education. We believe strongly that raising the base level of capability among our clients, among our competitors, and the public at large is key to our long-term success. It’s also a sort of civic duty for internet people, key to a fun and eventful future life online. Working with clients to teach them basic HTML concepts and syntax serves this goal very well.

HTML literacy is also a highly portable and valuable skill online. After years of people mucking about with HTML-alternatives like BBcode and worrying if users would break pages, more and more websites and services are allowing people increasing freedom to use HTML to communicate. Learning the lingo isn’t just going to help you post on your own site; it’s something that will make you a more powerful netizen all around.

For instance, MySpace made itself a smash in part by letting you do whatever the heck you wanted with your profile. By opening up the “real” language of HTML and CSS, they grew and deepened the connection with their user-base, inspiring a small cottage-industry in in profile-theming tools as well as some truly, uhh… unique, designs. But you can’t argue with results.

Certainly no one can force people to learn, and often times in a business or organization people have more important things to do in the short-run than puzzle out hypertext markup. That’s understandable, but our practice is build around working with people and on projects that truly come to life through the web. Sooner or later, that means speaking the native language, and it’s easier than you think to learn how to make links, lists, and turn text bold or italic.

Taking that fist step into HTML literacy is about more than moving beyond plain text. It opens a door to a deeper level of conceptual understanding as to how the internet works, which is really what we drive at with our clients: not just competence with HTML, but a more comprehensive procedural literacy for life online.