The Common Language Everyone Speaks

by Tom Johnson on Feb 10, 2010
categories: technical-writing

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, Shannon 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 Shannon 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 Shannon 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:

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:

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.