Adventures in Scenario-Based Documentation

August 16, 2011

Back in June, I posted about a new initiative my technical writing team planned to adopt. It’s called Scenario-Based Content, a strategy that fits our work as technical communicators into the abbreviated schedules typical in an Agile project.

If you read the June post, you’ll remember I was perplexed by the idea. I wasn’t sure how Scenario-Based Content was any different from the task-based content we were already developing.

In the time since June, we’ve had some training and opportunity to practice during a certification process, which I just completed today. My impression? Scenario-Based Content just may be the answer to several questions.

How are Scenarios Different from Tasks?

Scenarios should align with user stories. For example, “I want to recover my protected server from a disaster even though I don’t have the disaster recovery option.”

This user story was my certification project. The solution to recovering this server is not a single task. Rather, it is about ten tasks, about half of which are optional, depending on outcomes of prior tasks, as well as on the specific configuration of the environment where the disaster occurred. All of these tasks were already written and included in our product’s Admin Guide. But we never addressed how users might actually read those tasks or we’d have know how difficult they were to follow.

I took apart the monster section and organized it into baby tasks. My first requirement for certification was to design a flow chart that explains the scenario. This, as it turns out, was crucial for my own understanding of the process.

The process, as originally written, had so many conditions, I kept losing my place. Distilling it down to something that could be expressed by a standard diamond decision shape required nesting conditions, which in turn, showed me where to break out the various optional procedures.

Armed with a list of baby procedures, it occurred to me that I needed a mechanism for guiding readers back to the main path through the flow chart. I added a What Should I Do Next section to every task in the scenario.

Can Scenario Documentation Truly Fit Inside an Agile Cycle? 

I was skeptical about this until I tried it for myself. At the same time I was practicing for my certification, I was also assigned to a new product team. This new product has several sprints already scheduled. I read the user stories planned for each sprint and began setting up scenario content shells ( I don’t have a working UI yet). Right now, I have three major scenario shells, which I may further break down, once I see how complex the UI is that supports them.

What astonished me was how much of this new product I already understand and it was just kicked off. With our old process, I wouldn’t have reached this point until several months into the year-long production cycle.

Will Scenarios Document the Whole System?

In a comment left after my June post, “Techquestioner” said scenarios may not show you the whole system. I think this is true to a large extent but hasten to add I don’t think that’s necessarily a bad thing.

Here’s why:

The Admin Guide for one of my products is nearly a thousand pages. How frequently do technical communicators lament the fact that no one is reading our work? This is due primarily to our insistence that every detail be covered. The problem with that approach is most people will never have need for all of those details. For example, my product works on all Windows operating systems dating back to XP. But if some users are running Windows 7, they have no need for all the XP details.

Sure, we could debate publishing baby books for each OS version over the merits of single-sourcing, but the point remains the same – we’re giving them too much information.

Scenario-Based Documentation focuses ONLY on the information needed to solve the problem described in a very specific user story. If there are twenty fields on a UI dialog, but only three of them are needed in a particular scenario, then only those three are documented. The balance will be documented in some other scenario until, eventually, all fields are documented.

Aren’t We Doing Double Work? 

Got me there. Here’s one problem with Scenario-Based Content: Help Systems are still UI-centric. If I click a Help button on a screen, it means I need help on that screen. I don’t want to have to click through a dozen scenarios until I find the one that contains the instructions for completing the one field I need.

So I still see us documenting software screens separately for Context-Sensitive Help systems in addition to Scenario-Based Content development.

Based on what I’ve practiced and applied so far, I like the Scenario-Based Content approach.

How are you documenting software in Agile environments? How are you addressing the problem of fitting UI-centric Help screens into a scenario-based model of development? 



  1. A very interesting post. Scenario vs. Task sounds like splitting hairs at first, but conceptually they are different. I suppose you could look at it as multi-task vs. single task. I also have a massive Admin guide. It is UI-oriented. I inherited it from the previous writer and added procedural task-based content as needed and when it seemed appropriate, but because the entire system is flexible, it’s like documenting tinker-toys. I can tell you what the individual pieces do, but telling you what to do with them to make something is difficult without knowing what you want to make. Most of this is covered in the course material which walks through multi-step instruction sets for designing functioning samples.

    In general, I’d like to include more context sensitive help, and your post reminds me that I need to speak with the developers regarding this. They’re currently in the design phase for a new ‘lighter’ version of the product. It would greatly benefit us if those individual UI pages contained context sensitive links into the help system that will end up accompanying this product. That’s not too difficult since the guides will be HTML and PDF, and I can easily insert markers for generation as anchors in the Framemaker source documents. First, though, we need to determine what the tasks will be – and in general I think I should provide them with UI descriptions first and then cross-link to tasks that are provided on the UI description page under a simple heading like “Possible Implementations” or something like that. You know, “what you can build with this thing.” Since I don’t know if they just want a simple definition of the UI control, or an example of what can be made with it, I’ll provide the UI definition first, and give them links to procedures that use that UI element.

    • Thanks for commenting. I like the tinker toys analogy. It’s perfect for describing this initiative. We do a great job of documenting each procedure but not so great a job at putting them together into larger solutions. Whose ad slogan was “What do you want to build today?” That’s the end game- keep in mind the user’s problem and give them the info they need to solve it, rather than spread it over an Admin Guide, a Command Reference, a Help System, etc.

  2. Real-world use is the foundation of agile-scrum development. So, using scenarios to document software in Agile environments should be a natural match.

    Creating the process flows could be helped by a code analyzer-visualizer. I can’t speak for the stand-alone documentation and user help tools, but maybe the integrated development platforms have extensions that help tech writers create the whole range of user content.

    • Scenario-based writing seems to be quite an intriguing concept. I guess as user advocates, technical writers always try to give users what they need. It’s easy to get bogged down with technical complexity though and end up including a lot of ‘clutter’. Right now I’m writing manuals for the manufacturing industry and there’s so much detail that can be included on the electronics and mechanics that I have to critically assess the usefulness of including them. It comes down to and audience analysis and possibly having different flavors of a manual for each type of audience.

  3. Patty, you mention about the certification for scenario based writing. Could you provide the details of the certification.

    • The certification was internal. We were assigned mentors who helped us examine legacy content for disconnected but related topics. In my example, all the tasks required to complete the stated objective were spread across many books. It’s like trying to cook a holiday meal. All your recipes exist in different books. Desserts may be in one cookbook, your entrees written on index cards from a relative. In this case, the scenario would combine all these recipes and steps required to cook the entire meal into a single article. Our mentors reviewed our efforts and eventually ‘passed’ us as certified.

  4. […] In Online Documentation, unlike print matter, there is room for Use-Case. Scenario-Based Documentation is popular now, so learn to make it your friend. The SBC is an online user’s friend. Embrace the SBC. […]

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: