Organizing Content as Story [Organizing Content #17]

With my ongoing series on organizing content, I left off at the question of whether blog platforms would outperform help authoring tools as a way to organize content for web environments. I had a lot of thoughts about that topic, and actually created a blog theme for a documentation project as a test, but recently I received a new project on my plate, and my attention has shifted to another angle on this same series: organizing the content within the topic itself.

I’ve been listening to Alan Porter’s presentation on “What Tech Docs Can Learn from Comics,” which he gave at the 2009 STC Summit. I was also reading his detailed post on the same topic on The Content Wrangler. Alan emphasizes the importance of implementing two main elements from comics into technical documentation: story and visuals.

One can hardly disagree with his recommendation. Any time you add either story or visuals to your content, the appeal of your content increases. When you combine story with visuals in sequential ways, as comics do, the appeal of your content increases dramatically. In this post, I’ll focus on this first point: organizing content as story.

What Is Story

Alan says a story (or narrative) includes a beginning, middle, and end. You take the reader somewhere new through a series of events.

A story has a beginning, middle, and end

A story has a beginning, middle, and end

Alan explains,

The second fundamental of comics is the idea of narrative [or story]. Narrative should drive and guide the reader / user along on a journey. All communication is story telling (and that is perhaps meat for a future blog post), 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.

Story can be defined and described in various ways. I like to define story as any attempt to overcome a conflict, and a good story is one that requires some change to overcome the conflict. To fit this with Alan’s definition, in the beginning of the story, the protagonist encounters a problem or has some quest or yearning. In the middle, we learn what steps the protagonist is taking to resolve the problem or realize the yearning. In the end, we have the resolution.

The Element of Change

In a good story, the resolution always brings about some type of change, or comes about because of change. If you listen to stories on The Moth podcast (a storytelling podcast), you’ll constantly hear this element of change near the end of each story. For a story to feel meaningful, the protagonist always changes as a result of the conflict. Without this element of change, the story feels flat.

In technical documentation, achieving that element of change is difficult. In almost all technical documentation, the reader is the protagonist, since our point of view is second person (“you”). You (the reader) have a problem. You may be frustrated and ready to punch your fist through a door because of this problem. Through the help topic’s steps and information, you find a solution that solves your problem. Hooray, you’re much happier and complete now. That’s the basic transformation.

Tech doc will probably never go beyond this simplistic transformation to achieve anything of literary significance. For example, we’ll never have users feel a sense of the fragility of life or the meaninglessness of existence. Because of that, I think it’s best not to dwell on the transformitive element of story when applying it to technical documentation. Instead, it’s more practical to focus on the initial catalyst of all story: the problem.

Focusing on the Problem

A problem of some kind usually drives and gives rise to the story. But isn’t every help topic by default the answer to some problem? And aren’t users coming to the help content with a problem already in mind? Do we need to explicitly supply the problem, since it’s already apparent in the user’s mind?

Yes, your protagonist already has a problem. That problem is what is fueling his or her path through the help. But it can still be helpful to state the problem explicitly so that users can connect their problem to the solution you describe.

An Example

Let’s take a look at an actual example. Last year I wrote the following help topic for a calendar application that my organization is going to be using. Here’s the topic:

Subscribe to a calendar

Before you can see events for a calendar, you must subscribe to a calendar. When you subscribe to a calendar, it appears in the right column in a unique color. Your ward or stake may have dozens of calendars available, but you see events only for the calendars to which you subscribe. To subscribe to a calendar:

  1. In the upper-right part of the screen, click Options, and then click Manage Subscriptions. The list of calendars appears with three categories: WARD CALENDARS, STAKE CALENDARS, and OTHER CALENDARS.
  2. Click Subscribe next to the calendars you want to view.
  3. In the upper-left part of the screen, click Calendar to return to your calendar home page.

Events from the subscribed calendars appear on your calendar. The calendar name also appears in your list of Subscribed Calendars in the right column.

The topic probably looks like a lot of topics in a help file. In a rather boring way, it explains how to perform a basic task in an application.

This topic doesn’t feel like a story. The problem is briefly mentioned at the beginning — “Before you can see events on the calendar, you must subscribe to the calendar.” And the resolution is fulfilled through the steps. But if this is the extent of story in tech doc, we may as well forget about using story as technique, because all documentation looks about like this by default.

Let’s try to rewrite the same topic with a larger emphasis on the problem. Since story usually starts with a problem (or a yearning), if we emphasize this element more, and provide a stronger resolution at the end, it will feel more story-like. Here’s that adjustment:

See Events on Your Calendar

When you first log in to the calendar, you will notice that it’s blank. No events appear, even though you may know that calendar content is available. Although it may seem like the calendar lacks content or isn’t yet set up, actually there may be plenty of events on the calendar — they are simply hidden. In order to see calendar content, you must subscribe to the calendars you want to view.

To make events appear on your calendar:

  1. In the upper-right part of the screen, click Options, and then click Manage Subscriptions. The list of calendars appears with three categories: WARD CALENDARS, STAKE CALENDARS, and OTHER CALENDARS.
  2. Click Subscribe next to the calendars you want to view.
  3. In the upper-left part of the screen, click Calendar to return to your calendar home page.

Events from the subscribed calendars appear on your calendar. The calendar name also appears in your list of Subscribed Calendars in the right column. You can now view the details of each event. You can also toggle the calendar event display on or off by select the calendars you want to view or hide in the options panel.

The only substantial change I made was adding another two sentences about the problem in the introduction: “When you first log in to the calendar, you will notice that it’s blank. No events appear, even though you may know that calendar content is available. Although it may seem like the calendar lacks content or isn’t yet set up, actually there may be plenty of events on the calendar — they are simply hidden.”

I also changed the title from “Subscribe to a Calendar” to “See Events on Your Calendar.” And I added another sentence in the resolution.

Strategies for Story

It might generally be good practice to kick off each topic by describing in detail the problem that the topic solves. Although I said that the user brings the problem/conflict to the table already, putting ourselves into the mindset of a “problem-solution” format will help focus our help topics on the pain points and other most likely desired information. Explicitly stating the problem, rather than simply explaining the basics of an application, helps us maintain our focus as technical writers in the right direction: the user’s story.

On another level, though, explicitly stating the problem in detail helps the user connect his or her problem to the solution. In the above example, the user senses frustration that the calendar is blank. How would seeing a topic that says “Subscribe to a Calendar” help the user know that this is the answer to his or her blank calendar problem? There’s a cognitive disconnect if you omit the problem from your topic. Without the explicit statement of the problem, any topic might be the answer to a blank calendar. “Finding a Calendar,” “Troubleshooting Calendar Events,” “Adding Calendar Events” — these topic titles all seem like likely candidates for the user’s problem of not seeing calendar events.

Now what about the title, changing it from “Subscribe to a Calendar” to “See Events on Your Calendar.” Most readers don’t come to help files looking for basic information. They come when they have a problem. So shouldn’t our help be centered around this problem mindset and language?

That seems logical, but most help topic titles simply list tasks or actions that aren’t necessarily problems. I am not sure that changing the help topic titles to describe problems works all the time, but the general formulation of topic titles should represent the user’s problem in a closely connected way.

Although a poignant story in the literary sense will probably never be something we can achieve in documentation, structuring help topics with a detailed problem in the beginning can help make topics more story-like.

follow us in feedly

Adobe RobohelpMadcap Flare

This entry was posted in findability, general on by .

By Tom Johnson

I'm a technical writer working for a gamification company called Badgeville in the Silicon Valley area in California. I'm primarily interested in topics related to technical writing, such as visual communication (video tutorials, illustrations), findability (organization, information architecture), content development (DITA, testing), API documentation (code examples, programming), web publishing (web platforms, Web design) -- pretty much everything related to technical writing. If you're trying to keep up to date about the field of technical communication, subscribe to my blog either by RSS or by email. To learn more about me, see my About page. You can also contact me if you have questions.

7 thoughts on “Organizing Content as Story [Organizing Content #17]

  1. Bob Chapman

    An advantage to the story narrative approach would be the user becoming a part of the narrative. They have blank calendars. They want events on their calendars. It becomes personal.

  2. Karla

    Someone is always trying to reorganize my help files. What works for one guy doesn’t work well at all for the next. I can ask 5 different people who use it how they use the help and get 5 different answers. The best thing to do–since people don’t read help the way they read a novel–is to have a good search function built in. Sadly, I have yet to find a “single source” solution that has good search functionality. I’m left to add endless Index entries so that I our Google search on the web site can find it.

  3. Scott

    A thoughtful and timely post. I have been thinking and reading about storytelling in technical communication for a while, and have had trouble envisioning how it could really work. This post walks through a good example.

    I am a firm believer in making documentation task-based, and storytelling is another way of looking at this method. Users generally view documentation with an “I need to…” mindset, not a “What are all of the possible ways this feature might apply to me, theoretically?”.

    One potential pitfall with storytelling: people don’t sit down with technical documentation for a good read. It’s important to make sure the documentation is concise and doesn’t mince words. The user wants the clearest, simplest way to the end, not a flowery and inviting tale of wonderful prose. Storytelling doesn’t have to be lengthy and circuitous, it just has to be complete (the example above does this well).

  4. Larry Kunz

    As is so often the case, it depends on who you’re writing for. I think that novice users will like the second approach — the one in which you describe the problem in more detail, and in a narrative form (“you will notice that it’s blank”). But experienced users will prefer the first approach. They already know the problem; they want to cut to the chase. All they need is a very brief problem description so they’ll know they’re reading the right topic.

    I do think that changing the title from “Subscribe” to “See events” was a big improvement, no matter which audience you’re writing for, because it mirrors the story that the reader has in mind.

    You’re right that as technical writers we’ll never get to tell any really big stories. But writing a big story in a step-by-step, how-to format might be a fun way to practice honing our skills. Just imagine: the story of Odysseus with steps, sub-steps, and callouts to reference topics that contain additional information.

  5. Tony Chung

    I’ve been away from this series for too long. Thanks to @JanetSwisher for pulling me back in to read a timely topic. I’ve just finished reading Donald Miller‘s A Million Miles in a Thousand Years, where he talks about the struggle with living a story worth writing about. Our technical documentation, while being far from great literature, need not be dry and boring. Rather, it should engage the reader to interact with it and act on the material discussed in the topic.

    Unfortunately, your second example may be a little too involved. I don’t think the solution necessarily requires more words. To the contrary, I believe fewer words are required—the solution needs the right words.

    I study songwriting through Pat Pattison‘s books, and had the pleasure of attending a workshop at a beautiful river rafting resort up near Boston Bar, BC. As the river rushed below us, we analyzed good song lyrics and found they all shared a common element: Regardless of the length of the song, the words were chosen specifically to evoke imagery that brought a listener into the work.

    With our writing, we need to write less about what we think, and find common ground to encourage our users to participate in the discussion. Kind of like what you do. ;-)

  6. Robert Desprez

    Interesting blog post, Tom. I just read author Daniel Pink’s book A Whole New Mind. In it, he suggests that workers in the Western world will have to incorporate more of the right-brained skills, such as design and storytelling, to differentiate ourselves and even stave off job losses.

    I tend to agree with you. As technical writers, we can improve to incorporate elements of storytelling in our content. Here’s my related blog entry: http://tinyurl.com/2c3mnqq

  7. Pingback: The Story-Telling Trend | Release Notes

Comments are closed.