I'd Rather Be Writing » power users

The Common Language Everyone Speaks

Tom Johnson — Wed, 10 Feb 2010 15:04:03 +0000

Several weeks ago, I was reading something that caused me to worry. A line in a scriptural narrative biography tells how his father taught him in all the ways of right. As a father, I thought about what I had taught my children, and it wasn’t much. They weren’t going to become Enochs from anything I showed them. Football on Sundays, basketball during the week, too much TV, long absences at a remote job, lots of time sitting at a computer doing, from their perspective, who knows what. I’m not sure I’m teaching them much of anything.

This bothered me. As a good practice, we’ve tried rounding up the kids to read before. But each time this proved somewhat disastrous. The problem is the wide range of ages. I’m 34, Jane 32, Sally 9, Susan 5, and Spot 3. Try holding a meaningful discussion when everyone is at a different comprehension level. What Susan can grasp isn’t on the same level as Sally. And Sally is far beyond Spot, and so on, to say nothing of Jane or me.

The situation isn’t too unlike the problem with technical levels and user documentation. Power users need one kind of documentation, beginners another. It’s hard to satisfy both groups with the same content.

Or so I thought. I haven’t solved the dilemma with user documentation. But with my little family, I’ve learned that story is the common language that everyone speaks. Regardless of age, when you start telling a story, everyone listens.

So we’ve stopped reading by the line. Instead we focus on the story. I read ahead, get the details of the story down in my mind, and then narrate it to my children. Sometimes Jane tells the story. Whereas before Susan would mischeviously close my book, she now listens eagerly. Sally listens and retains the most minute detail. Spot plays quietly with barbie dolls.

When we think about writers who are gifted with language, too often the discussion revolves around articulate expression, the ability to paint vivid imagery, or some other literary talent. Despite these flourishes, the most powerful form of language is story. Story is what has meaning. The stories you tell about yourself, the stories you learn about the world around you, and the stories others tell you form your world view and shape how you understand and interpret nearly everything that happens to you.

Story and Documentation

Story, or narrative, is not a stranger to the world of documentation. As I said, story is the language everyone speaks. In a recent post on The Content Wrangler, Alan Porter says narrative is one principle we can learn from comics and apply to documentation. Alan writes,

The second fundamental of comics is the idea of narrative. Narrative should drive and guide the reader / user along on a journey. All communication is story telling [...] and in story telling your narrative must have a beginning, middle and end. Even if you use a topic based authoring approach like DITA, each topic should be a ‘story’, the reader should be guided through the information and know more at the conclusion than they did at the start.

Alan’s assertion that “all communication is story telling” is a strong one, and much of it hinges on his definition of story. To some degree, a story must have a beginning, middle, and end, he says. He gives the following example of story from Chrome’s comic documentation:

An example of narrative in documentation

If you strip out the visuals and just leave the text, is that story? What really is story beyond simply having a beginning, middle, and end?

To rewrite the above into a more narrative form, it might look like this:

As you surf the web, much of your experience is defined by your browser. But browsers crash when they can’t load scripts or handle the heavy file sizes of websites. Rich media, in the form of video, graphics, and sound, can make your pages load slowly and freeze up your memory. Malicious scripts, worms, and other malware can pass from your browser to your computer, infecting your system with viruses. To avoid these problems, you need a stable, fast, and secure browser. That’s why we built Chrome…

To emphasize the story, I tried to highlight the challenges that you (the protagonist) face when you cruise around the web with your browser.

To be a good story, though, you need several other elements. Good stories start out with some kind of conflict, for sure. This gives the protagonist purpose. The initial conflict sometimes creates other conflicts, which then cross into each other, complicating the situation. The resolution often comes about as the protagonist changes. Without some change in the protagonist’s attitude, stories feel flat.

To make this a good story, then, I would need to talk about the effort to create Chrome, the challenges they faced, epiphanies at moments of absolute frustration, and other flashes of insight that helped make the connections and leaps necessary to build the browser.

Another Approach to Story and Documentation

Although the Chrome example works, much of documentation involves procedural steps, not background on how or why an application was made.

If story is the common language everyone speaks, and the most powerful form of language, what should the role of story be with procedural, step-by-step documentation?

Some procedural topics could actually be written like the example above, setting out the problem and explaining how to solve it through the software you’re providing. Focusing more on the problem is a good strategy. Here’s a page out of the CSS Cookbook that does exactly that:

The CSS Cookbook starts out each how-to topic by defining the problem that the solution answers

Notice how the author begins by defining the problem. The solution then provides the answer to the problem. This problem-solution format is not unique in their approach. Almost every topic in the book is set up this way.

Imagining Persona-Driven Problem Scenarios

Another way to incorporate a narrative perspective into documentation is by imagining specific use cases. Ginny Redish says to imagine not just the questions your users will have on a page, or the types of users who will come to your site, but to imagine specific users with specific problems.

For example, as you’re evaluating the content on your airline site, you may have already defined various personas for your users. But have you imagined your users with specific, real problems? John is a 34-year-old bank executive who needs to quickly cancel his flight to Hong Kong because of a family emergency. Now you have a problem that your content will attempt to answer. Sally is an impatient, scatterbrained secretary who was just thrown into her role last week and has to figure out how to set up a meeting in the new system by tomorrow morning. Again, you have both a persona and a problem.

Additionally, you can also integrate examples of actual users and common scenarios into the documentation. You could describe a typical scenario that Kate goes through to process bank statements in the system and what she does when the transactions don’t balance. This form of narrative is a technique often used in in e-learning.

The Story On and Off the Page

Although I’d like to believe otherwise, implementing story in the traditional narrative form will probably always be a challenge with technical documentation. Story thrives in the literary arts, not in manuals. However, although story might not apply to every page of instructions, every topic in your help can be an answer to a struggle the user is having.

In this sense, the user supplies the conflict and the documentation supplies the resolution. The change occurs when the user’s sense of frustration subsides with an aha! moment. Because of this, we cannot create the full story in our documentation. Instead, we’re only an actor playing a part in a larger story taking place on and off the page — the reader’s frustration with a problem, his or her turn to the help, and the resolution and change of attitude the help topic brings.

Blog Sponsors

A Microcosm of Technical Writing in the Kitchen While Cooking a Banana Cream Pie

Tom Johnson — Fri, 27 Nov 2009 08:20:41 +0000

As part of my contribution to the Thanksgiving dinner, Jane tasked me to cook a banana cream pie. She had a simple recipe already printed out.

The banana cream pie recipe

All the ingredients were available in the kitchen. The kitchen even had a double oven. I thought this would be easy, except it wasn’t. Because I suck at cooking. I hate cooking. If I cook, I need a “man’s cookbook,” one that cuts through the jargon and explains cooking concepts in idiot-like detail.

For example, try to make sense of this step:

Stir a small quantity of the hot mixture into the beaten egg yolks, and immediately add egg yolk mixture to the rest of the hot mixture.

This does not make sense to me. Pour A into B, and B into A? No reason given for this. Just do it. Why not simply pour A into B or B into A, rather than doing a little of both at nearly the same time?

Jane explained that this back-and-forth pouring of the hot custard would bring the egg yolks up to a warmer temperature slowly without causing the eggs to curdle. Oh, I said. Now I see, but that connecting logic was simply assumed in the instructions.

Here’s another place I tripped up:

In a saucepan, combine the sugar, flour, and salt. Add milk in gradually while stirring gently. Cook over medium heat, stirring constantly, until the mixture is bubbly. Keep stirring and cook for about 2 more minutes, and then remove from the burner.

Uhm, if I put dry ingredients in a saucepan on medium heat, they start to burn. Also, am I to mix the dry ingredients before adding them to the saucepan? How long do I have to stir this mixture — 5 minutes, 10 minutes? Bubbly means … slightly boiling, aerated, or some other state?

I stirred and stirred, but apparently not violently enough to get out all the clumps. I swear the mixture never got bubbly, but about 10 minutes into this step the mixture became thick and creamy — something I wasn’t expecting because there’s nothing in the instructions that indicated a dramatic change of state. Again, was I just supposed to know that the state would change, and that the changed state would mean the mixture was done?

I guess I had questions throughout. Here’s another place where I ran into a problem:

Slice bananas into the cooled baked pastry shell. Top with pudding mixture.

The recipe calls for 4 bananas. After I added 3, Jane said to stop because there wouldn’t be any more room in the pie. But perhaps the pie’s final shape was meant to be convex, rounded at the top like a small hill? And if I put the bananas at the bottom and the pudding on top, wouldn’t that be uneven? Wouldn’t it be better to mix the two somehow for a more even distribution?

Finally, the banana cream pie recipe made no mention about whipped cream. Am I supposed to whip cream and add it to the top of the pie, like I’m accustomed to seeing in coconut-cream pie? Or is the custard filling the cream component of the pie?

I repeated several times my desire for a man’s cookbook, one that would provide more details, more straightforward explanations, and more hand-holding.

Yet for Jane, she preferred the abbreviated, concise recipe style because she’s familiar with the terminology and methods. When a recipe says to prick a pie shell, she knows about how many pricks to make, how deep to make them, and how much space between all the pricks. When I see instructions to prick a pie shell, I’m thinking up all kinds of scenarios about what this could mean.

Is not documentation exactly like this? You have the novices and the power users, and the instructions will inevitably frustrate one and appease the other.

Perhaps this is why I like online formats so much, because they allow you to add the extra detail in links pointing to additional pages, in drop-down hotspots, or through little information pop-ups. You’re not restricted by space.

My pie turned out well in the end. I’m guessing there was some wiggle room and leniency in the instructions, which is perhaps why some seemed vague. Overall, the Thanksgiving cooking experience was a perfect microcosm for the world of technical writing.