Example Title
Me: “Pro tip: When your tutorial is abstract and insists on filling every field with ‘example’, you are not teaching your users anything. #expressionengine”
Drew: “Can you elaborate on this? I’m creating an actionable tutorial for MagicList and I’d like to understand what doesn’t work.”
Yes. Totally. This needs to be more than a tweet, though, but less than a blog post.
So consider this dashed off.
I just started learning ExpressionEngine, a content-management-slash-blogging platform that I have been told is truly awesome. A lot of people I truly respect and admire have thrown their weight behind it, and while I do still believe in the idea of ExpressionEngine, I am indeed experiencing frustrations in getting up to speed as to what all these knobs and buttons actually mean.
ExpressionEngine is extremely powerful, and the myriad tools in its control panel have fairly complex relationships with one another. Unlike WordPress, however, ExpressionEngine doesn’t work right out of the box. Which is fine; each piece of software serves a different purpose. ExpressionEngine is a tricked-out means to manage a website while WordPress is a turn-key blog that can be arduously turned into a CMS.
Given the complexity of things within ExpressionEngine, it becomes all the more important that it has good documentation, especially in the ramp-up for a new user. And, especially since that user just spent $100-$300 on this new ephemeral thing, even when surrounded by a sea of free options, it becomes absolutely essential that the new user of ExpressionEngine feel as though they are kicking ass right out of the gate.
So. Upon installing and configuring my installation of ExpressionEngine, I was met with a sad, lonely, empty page when I typed in my development URL. No HTML, no nothing, even when viewing source. As a user, a user who is now $100 lighter, I want to fill that blank canvas as quickly as possible with something great.
I turned to EllisLab’s own Getting Started with ExpressionEngine guide to, well, get myself started. It turns out there are a fair number of steps that stand between me and my “Hello World.”
So here’s the rub. ExpressionEngine requires, or at least its user guide suggests it requires, that you do a number of things within the control panel before anything is going to appear on your website. Following the steps, you need to create a Custom Channel Field Group, a Custom Field, a Category Group, a Category Name, a Status Group, a Channel, and finally a Template Group.
Now, I’m ripping through these steps, skipping paragraphs of text and looking at screenshots, like a kid tearing through wrapping paper on Christmas, because I know there are some real banger presents at the end of this. In their haste to get people up and running, however, EllisLab has neglected to actually impart any knowledge as to how all these different elements relate to one another, what they do, and why they’re important.
The Getting Started guide for ExpressionEngine is written in the abstract, using the word “Example” for all seven of these critical elements. By the end of the tutorial I have created a Field Group named “Example” which contains a Field called “Example Body”, a Category Group called “Example” with a Category called “Example News”, a Status Group called “Example”, a Channel called “Example”, and a Template Group called “Example.”
Phew. That’s a lot of Examples. The challenge with using the same name for every item in a tutorial is that I, the user, develop no mental model for how these elements actually interact with one another.
What would have been far more valuable in this case would have been to base the tutorial’s content on a hypothetical scenario… say, building a news website. That way, you can name each element accordingly, based on its metaphorical analog. I appreciate what EllisLab is doing, in that ExpressionEngine is so wickedly flexible it can be used for managing streams of any content. For the sake of the tutorial, however, I believe those layers of abstraction should be suppressed.
Rather than naming everything “Example”, which does nothing to help my brain understand the relationships between these unfamiliar elements, I recommend that you use a familiar example and the objects and metaphors associated with it. To leverage the news example, Field Group becomes “Article”, Custom Field becomes “Article Body”, Category Group becomes “Sections”, Category becomes “Technology”, Status Group becomes (uhh, something?), Channel becomes “Home Page”, and Template Group becomes “Home Page Layout”.
It’s a small change, with a risk that it understates the sheer power and flexibility of ExpressionEngine. However, the modesty of using familiar examples in a tutorial will go a long way in helping new users understand these unfamiliar relationships. Only after they’re ramped up and feeling awesome does it make sense to begin introducing them to the power under the hood.
