The Common Language Everyone Speaks

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.

Adobe RobohelpMadcap Flare

By Tom Johnson

I'm a technical writer working for the 41st Parameter in San Jose, California. I'm interested in topics related to technical writing, such as visual communication, API documentation, information architecture, web publishing, JavaScript, front-end design, content strategy, Jekyll, and more. Feel free to contact me with any questions.

18 thoughts on “The Common Language Everyone Speaks

  1. Patty Blount

    Agreed, Tom… Narrative and use of story anchor tech writing to something concrete for me… I think this is why I love the videos Common Craft do. They always start with a story so easy to relate to.

  2. Maeve Maguire

    Get outta my head! Earlier this week I posted a question on a LinkedIn forum (Technical Writer Forum) asking if others had successfully used stories in their documentation.

    Your persona example makes me think of user stories in agile development. Each of those user stories could be shaped into a persona and problem. With topic-based help, I guess each topic would have its own story…? Have to think this through a little more. Then there’s the idea of using that same story line for sales demos to tie it all together. But then is that overkill?

    Patty – I was thinking of Common Craft too. And they get around the illustration issue by using paper cut-outs and a white board. Brilliant.

    1. Tom Johnson

      I’ve always been curious about the term “user stories” to describe functional requirements in software design. User stories makes it sound much more interesting than they actually are (at least where I am).

      Although knowing exactly where and how to fit stories into documentation may not be clear, one thing I know: when you consider your application from different scenarios, personas, and problems, you write better help.

  3. Patty Blount

    I don’t think it’s overkill at all, Maeve. I think it unifies all the various information elements together… sales pitches, user doc, help, etc.

    I love Common Craft’s paper cut-outs and white board usage; I think the simplicity of it is just another layer to the message – making the complex easily understood. Brilliant is right!

    But getting back to the topic, user stories remind me of that old nugget, WIIFM… What’s In It For Me… Hm. Could be a blog post in here somewhere…

    Tom, I remember you saying more stories in your blogs was a goal for 2010. I think I might take on the same goal.

    1. Tom Johnson

      It always surprises me when people remember what I wrote a couple of months ago. Yes, stories in posts are one of my goals this year. It makes writing both harder and easier. Harder because I have to see the story in my mind first, and sometimes it never comes together. But easier too, because when the story does come together, it’s a lot easier to write. Maybe by the end of the year I’ll have it down.

  4. Milan Davidovic

    “Good stories start out with some kind of conflict, for sure. This gives the protagonist purpose.”

    I’ve heard it described differently — the protagonist already has a goal, but obstacles or conflicts arise that threaten the protagonist’s achievement of the goal. One of the writer’s jobs it to get us to care about the protagonist so we’ll read the story and find out how s/he overcame the obstacles/conflicts.

    More here:
    (“Writing for Story” on Google Books)

    So, how might you translate this to technical communication? This may be a challenge.

    1. Tom Johnson

      Milan, thanks for deepening the perspective on story here. I think you’re right. Without having a goal, the obstacles or conflicts that arise wouldn’t be as significant since we wouldn’t care about the protagonist’s goal.

  5. Patty Blount

    WIIFM again… Introduce the story’s User, describe his problem, show how product usage solves the problem. Answering the what’s-in-it-for-me question gets people to care about the protagonist, who in our case, is “Every User” in a sense.

  6. Milan Davidovic

    @Patty — sounds facile to me, but if you can hook your readers and keep them through to the end with that, then good. I suspect, though, that if writing good stories really were that simple then there’d be less advice out there about how to do it. But as I said, if it works for you…

  7. Alan J. Porter

    Hi Tom –

    Thanks for the mention and the link to my recent article on The Content Wrangler.

    My definition of story does go beyond it just having a beginning, a middle, and an end. – I also include that a story should take the reader along on a journey to discover something. In fiction that journey is often a vicarious one as we follow the protagonist (and in good fiction hopefully discover something about ourselves as well), in non-fiction and technical documentation, the journey is one of gaining knowledge.

    Although I didn’t include it in the article you linked to, I also think that we should think about things like how ‘conflict’ etc. applies to technical writing.

    I posted a blog entry last year on <a href= 10 Commandments of Storytelling as applied to Tech Doc? which covered some of the same ground.

    BTW I loved this line and will be quoting it frequently from now on.

    Story is the common language that everyone speaks. Regardless of age, when you start telling a story, everyone listens.

    1. Tom Johnson

      Alan, thanks for expanding on what you mean with the beginning, middle, and end. In your blog post, you elaborated by saying, “The narrative should guide the reader through the process, or information, in such a way that it flows logically, and that at the end they know more, or have achieved more, than when they started.” I like that.

      I think I sometimes ove- value conflict as the shaping force of a story. It’s really this realization (or knowing more at the end) that takes place that can also give shape and intrigue to a series of events.

  8. Ivan Walsh


    Another suggestion is that ‘you are your own story’.

    For those who plan to develop a profile online (or thru videos) how you share your life story helps cultivate a readership.

    Notice how Brogan does it, for example, v effective.


  9. Bill Kerschbaum

    In tech doc, the reader is the protagonist – so I’m reading my own story. Makes me think of those “choose your own adventure” books I loved as a kid. Hmm…just for fun, I wonder how I could explore that in my tech docs?

  10. Bill Kerschbaum

    Incidentally, the idea of story is a big deal in scientific research papers. Researchers are horrible writers, and one of the ways I try to get them to think about their writing is in terms of story: Show the problem, show that it’s significant, and show how you can solve it. Present it like a story.

  11. Patty Blount

    I agree, Bill… that’s similar to my earlier post regarding WIIFM… or “what’s in it for me”… Tying this back to fiction writing, I think our goal is to make our protagonist sympathetic.

    To evoke sympathy in readers, we as writers must present the protagonist as someone “just like me” and then introduce the conflict.

    I really love the parallel here, think it’s a brilliant post, Tom.

    1. Tom Johnson

      I like the idea of presenting the protagonist as “someone just like me.” Interesting technique. About the only way I can think of doing it is through sample scenarios with personas.


Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>