Tutorials can help stop the Zombie Stare. You know the one. Look for drool-covered keyboards.

Writing good tutorials isn't easy. Here are some tips.

Reader profile

Decide who you're writing for. DrupalZombie articles are for humans who:

• Know HTML 4 moderately well.
• Know CSS 2 basics.
• Know what JavaScript does, maybe can write an alert.
• Know database concepts like "table" and "row."
• Can install Drupal 7.
• Know basic Drupal concepts like modules, themes, users, permissions, and content types.
• Know basic site administration.

Tutorials written for this audience are different from tutorials for seasoned developers.

Advice: don't season developers. Zombies love seasoning. Some brains are soooo bland.

Goals

There are different types of tutorials. Two common types are mental model tutorials, and task tutorials.

Mental model tutorials explain how something works. To solve their own Drupaly problems, people need accurate mental models. The article How theming works (maybe): part 1 is a mental model tutorial. It doesn't talk about a particular task.

IMHO, there should be more mental model tutorials for the Big D.

Task tutorial help readers do something specific. Configuring CKEditor and WYSIWYG: Zombie fighters for users is an example. Task tutorials help readers build mental models, too, in the context of a particular goal.

The best task tutorials explain the problem solving process, that is, not just what to do, but why. They start by showing the end result. If needed, they explain why the end result is Good. If there's more than one way to do things, the tutorial can explain the choice. The Removing vs. hiding section of Hiding the comment form's input format selector: A zombifying experience is an example.

When you're writing a tutorial, understand your goal, and tell your readers what it is. Remind them, as you go through the tutorial.

Explain in text and images

Explain in text, then add an image for the same concept, and explain the image. Presenting the same info in different ways helps humans make more connections between ideas. More connections, better understanding and memory.

For example, look at the Removing vs. hiding section of Hiding the comment form's input format selector: A zombifying experience.

Recap

Like programs, tutorials have multiple levels of detail. There's the overall structure, then detail for each section. When you've been in the detail for a while, jump back up and remind readers of the goals, and the big steps. Speaking of tutorials-are-like-programs...

Metaphors

Metaphors recruit an existing mental model from one context to help build a mental model for another context. For example, How theming works (maybe): part 1 likens template files to Mad Libs.

Be careful here. Readers can take metaphors too far.

What people don't know

Readers don't know what you know. Not just the topic of the tutorial, but lots of other things.

For example, many people haven't worked with the command line. Particularly young whippersnappers. Drush: A zombification remedy talks a lot about the command line, what it is, and why it is still used. In fact, the Drushly part of that article is shorter than the mental model build up.

(I might break that part out into a separate article.)

The "expert's blind spot" is where people who know something forget how hard it was to learn it. Or worse, experts forget they know something at all.

Huh?

Sometimes expert knowledge is so automatic that we forget that it exists. We just do stuff automatically, forgetting that we know how.

Keep the reader profile in mind. Statements like "go to your home directory" make no sense to many people raised in GUI-land. They'll better understand things like .bashrc paths if they know what a home directory is.

Language

Short sentences and paragraphs. Like these.

IMHO - use informal grammar. Not mistakes like "They is you're friends." But ending sentences with prepositions is something up with which we can put. (Apologies to Winnie.)

Sprinkle humor around. Too much is distracting, but a little helps lighten the mood. Reducing anxiety is a Good Thing.

That's all for now

Hints for writing tutorials:

• Decide who you're writing for.
• There are mental model tutorials, and task tutorials. Both are worthy antizombie tools.
• With task tutorials, explain why the problem was solved that way. Give a little mental model.
• Explain in text, and explain in images.
• Readers don't know what you know. They don't know things you have forgotten you know.
• Informal language.
• Humor.

Got more suggestions? Please comment.