Narrative Workflow Topics: Helping Users Connect the Dots Among Topics

by Tom Johnson on Sep 12, 2013
categories: findability

I'm continuing my series of posts addressing why users can't find information in help and what to do about it. The following reason received a high number of votes:

The answer is an isolated task, but the user needs a more connected beginning-to-end workflow.

This answer has received 66 votes. So far, the highest number of votes any response received is 78. (By the way, if you haven't taken the survey, you can still do so here at the interactive poll.)

Leah Guren highlighted the problem of interconnected tasks in her talk at the UA Europe conference, noting that many smartphone guides might explain how to look up contacts, and also how to make a call, but not how to look up contacts while you're on a call.

Help is typically written in a modular fashion. Most help topics focus on a specific task or concept, giving you a lot of detail and step-by-step instruction for completing that particular task.

But the task is often only one part of the solution. A user may need to leverage several tasks in context of each other to solve a problem.

An example of interconnected tasks

For example, at a previous organization, I wrote documentation for a meeting management tool. Secretaries would need to create a meeting, add items to a meeting agenda, send out the previous meeting's minutes for votes in preparation for the meeting, route non-meeting items to an external voting process, arrange meeting items on an agenda, and so on — all within this web-based tool.

I wrote each task as a standalone help topic in a section called "Managing Meetings." The model seemed fine if the secretary was already familiar with the application and just had a specific question, like how do I cast a vote for a meeting member who is on vacation? -- or something similar.

But new secretaries or secretaries unfamiliar with the tool needed a lot more hand-holding. It didn't make sense to give them all of these standalone topics. How would they know which order the tasks were to be completed in? Were all the tasks necessary to their role, or were some optional? When should a secretary complete each task?

Not every committee followed the same meeting process either. The tool was designed to support both formal and lite committee processes, with some committees voting and recording minutes, and others just displaying ad hoc agendas.

What was missing in the help file was a workflow or scenario-based topic. So I wrote some narrative workflows. The workflow topics went something like this (each bold-formatted word would be a link to a topic):

Mark is a secretary for the ACME committee. The committee has a meeting coming up next week, so Mark creates a new meeting and adds it to the calendar. Mark gathers agenda items and adds each item to the meeting. Mark also estimates the time for each agenda item and also adds times for guest visitors or other meeting events.

On the day of the meeting, Mark displays the meeting in agenda view on the projector while opening a second monitor to take notes. During the meeting, for each agenda item, Mark routes the item through several workflows depending on the nature of the item and the committee's discussion. Mark can route an item through the voting workflow, the postponed workflow, or the resolution workflow. After the meeting, Mark closes the meeting and sends the minutes to all members for their review.

When the members finish voting on the minutes, Mark archives the minutes. If any committee members are out of town, Mark can vote on a committee member's behalf.

See how this topic differs from the normal task-based topics? This is a workflow that tells the story of how the product is used. Most software has similar workflows for the user to follow.

Writing documentation for programmers is somewhat similar. As you reference techniques in an SDK, for example, you might say something like, "Now we leverage the length method to count the characters in the string, and then we use the push method to add it to an array and so on.

Programming builds on concepts and techniques, and it makes sense to link back to these other techniques as you explain how someone might use the techniques in context of each other. Simply having access to a list of methods with little understanding of how you use methods in context of each other requires the user to do the work of figuring out how it all fits together. Workflow topics explain how a person uses the various tasks in a harmonious order for a specific end.

To better understand the importance of workflow topics, consider a couple of analogies -- with orchestras and connect-the-dots patterns. A flutist may know how to play the flute, and a drummer knows drumming, and a violinist knows how to play the violin. But do they know how to play in context of each other to create the sound of an orchestra? That's what a workflow topic does: it teaches users how to move from a single instrument to an orchestra.

Or consider connect-the-dot patterns. It's easy to make a straight line here, a curved line there, a right angle in another spot, but how do you bring all of those different shapes and lines together in context of each other to actually draw a picture? That's the brilliance of connect-the-dot pages. They put all of those disparate lines in a sequential ordering that makes sense for a specific end goal (which, in the following image, is a picture of an elephant).

The Problem of Linking

I think most of us would acknowledge the need for more narrative workflow topics. It's a wonder why we don't see more workflow topics already. My guess is that once we get so accustomed to working in an application, we become immune to the needs of a beginner user and forget about the person who needs more of a big picture and workflow before diving into the details.

Merely writing the workflow topics isn't hard. In fact, it's kind of fun because you tell a story of how your product is used, and if you can illustrate those steps, all the better.

But here's where it gets tricky. How do you handle all of those links? For most people who write on the web, links don't pose any special challenges. In fact, links are kind of an exciting prospect on the web because they feed Google with a lot of Pagerank. But most tech writers aren't usually thinking about SEO as much as just getting the information complete and accurate and ready by the time the feature ships.

For tech writers who do multichannel publishing, links become a headache. You might build a grid listing deliverables against topics to keep track of which deliverables contain which topics so that you don't link to a topic that isn't included in a deliverable.

For example, you don't want to have a link in your "Meeting Management Overview" topic that points to "Voting on Behalf of a Traveling Committee Member" if this topic isn't in your output.

To get around the hassle of manually tracking which deliverables will support which links to which topics, some writers rely on "relationship tables." These tables intelligently include links to topics only if the topic exists in the output.

Relationship tables sound like a neat idea, but in my opinion, they aren't reader-friendly -- the links get separated from the context in which the reader would expect the link, so the user has to know to look in the table below the content for links. You only hope that users reading about voting on behalf of traveling committee members will feel a need for more information and check the area they know to contain links.

Other tools like Flare allow you to run reports to see which links are broken or point to orphaned pages, helping you identify problems in the output. If you disregard the warnings, any links to non-existent topics will simply unlink the anchor text in the output, so it looks like someone forgot to hyperlink the text (e.g., For more information, see Voting on Behalf of a Traveling Committee Member.)

If you don't have to worry about multichannel publishing, and you assume that the web is a single repository for your information, you can dismiss all the concerns about whether a topic exists in your output and simply link to the topic.

The challenge with web-based platforms, however, is being able to see all the pages that a page links to as well as all the pages that link back to a page. Any time you delete or rename a page, you'll need to account for links pointing to the page and either update the links or add redirects.

Some platforms, like Drupal, are pretty smart about links. If you change a page name and URL, Drupal automatically creates a redirect from the old URL to the new URL. You can also add modules to see all the links pointing to the page you're editing. But managing links is still a very manual process.

I'll revisit links perhaps in the future, especially since I'm listening to a book on Google (In the Plex and plan to address SEO shortly. But I think it's enough to say that links embedded in the context in which they're relevant is the expected behavior on the web, reinforced by millions of sites that readers visit daily. If you implement any other linking strategy that may be more convenient for your content but which breaks readers' expectations (such as omitting all links in content to help lower-literacy readers "focus" better), I think the content will ultimately fail in a number of ways on the web.

How many workflow topics do you need?

Another question to address is just how many workflow topics you need. The example I gave at the start outlined a very targeted use case and audience, but most products satisfy a number of different business scenarios and workflows. How many workflow topics you need depends on how many different audiences (or personas) you're writing for.

If you've done some audience analysis and have a general idea that you're writing for 5 different types of users, you can simply repurpose these user types and any persona sketches into 5 narrative workflow topics.

Or if you're like me, you probably have a general idea of your users without any formal description of them. So here's a great opportunity to formalize the use cases and audience for your product into mini-sketches that show how your product might be used.

Where do workflow topics appear?

Once you've written some workflow topics, where should they appear? It depends of course on the workflow you're describing, but a good place might be an overview section at the beginning of your help sections or books. A narrative workflow provides a great overview topic, especially if you can link to all the pages within the section or folder.

If you have narrative workflow topics for each section, you could also stack these narrative workflows into various levels of detail. The extended example I provided earlier addresses managing meetings, but if the application itself is more broad, such as "administrative management," you might have a larger narrative workflow that goes something like this:

Mark is an administrative assistant for ACME committee. Before he sets up any meetings, he first routes work orders for facilities maintenance into the system. During the meeting, he evaluates the work orders. After the meeting, he escalates the confirmed work orders into the mainframe system to communicate with headquarters. Headquarters then takes action on the work orders. When the work orders are completed, Mark then adds notes on the previous meeting's agenda items to verify their completion.

Each of these links would point to narrative workflows that dive into greater detail. Of course it might be rare that one person would handle so many different tasks, and now the narrative is more of a list of possible actions rather than a story that shows sequence and workflow. But you get the point.

Why more narrative workflow topics aren't present in help material

I suspect that while narrative workflow topics would be a welcome addition to help material, they aren't as critical in help material as I originally expected. I wondered about this for a while, and the answer only occurred to me the other night while playing a complicated board game called Gingokopolis during "Game Night" at work.

One of the programmers brought the game from home, and although it looked visually interesting, it was pretty complicated. It took the programmer 20 minutes to explain how to play it. I have little interest in and ability with board games, but I wasn't the only one confused. As the programmer explained this rule and that rule and so on, his words became meaningless and empty until one person said, "Let's just start playing and people will soon get it."

About 15 minutes later, the person's prediction proved to be right -- I did start to understand the game in ways that were only possible from actually playing it. Now the rules and instruction started to make sense.

And so it is with help. If you read the manual before you use the application, it's the equivalent of someone explaining a complicated board game to you for 15 minutes before playing it. Only when you play it do the instructions become meaningful.

When people start playing around with an application, and figuring out its rules and concepts and interactions, eventually they'll start to get it but will also have more questions. At that point, help becomes meaningful and relevant.

By the time the user consults the help, usually the user has already gotten the gist of how the application works and just needs clarification around the details. At this stage with the user, narrative workflow topics may be too basic and redundant with what the user already knows. This is probably the real reason why users haven't been demanding narrative workflow topics in help material. Still, I think these topics have introducing new users to the general concept of "how to play."

Additional Reading

• End-to-End Scenarios