Using process-driven scenarios in documentation

In the October 2012 edition of Intercom, Morgan Dennis - information developer at IBM - describes a situation in which a team of writers at IBM developed a model for writing scenarios to be published with the first release of a new product. These scenarios were positioned as extended examples or use cases. 
When I started reading, I was anticipating an approach and solution very similar to the one I had chosen at Be Informed to document the latest version of their semantic BPM Platform. 

To me a scenario is a step-by-step description of how someone can reach a goal. So I was a bit puzzled when I read the following description in the article: 

When it was published, the scenario consisted of five topics:

• An overview describing the business problem and explaining, at a high level, how InfoSphere BigInsights could solve that problem
• A description of the business and technical challenges, which identifies common challenges that users face as they deal with their business problem
• An overview of the solution, written for an audience of decision-makers, that summarizes the high-level process of implementing InfoSphere BigInsights
• A detailed description of the solution, targeted to a technical audience of database administrators, which provides details about architecture and implementation
• A thorough explanation of the results and benefits of the InfoSphere BigInsights solution to potential customers

Exploring Users’ Expectations and Impressions Of Scenario Documentation
Morgan Dennis, Intercom October 2012, pp. 15-17

Looking at this description I can't help the feeling that this will result in a very formal, long text with the main message hidden in the third bullet. Although the article emphasizes the use of an extensive testing method, there are no results presented nor lessons learned from this approach.

Minimalism in scenarios

I have been reading a lot lately about minimalism, including of course John Carrol's book "The Nurnberg Funnel: Designing Minimalist Instruction for Practical Computer Skill" and the interview with John Carrol (by Nicky Bleiel) in the February 2013 edition of Intercom. In his interview with Nicky Bleiel, John Carrol talks about the active user: 

On the other hand, it’s ironic in that our studies of learning, and other people’s studies of learning, led us to a concept of the active learner, the active user. Meaning that people need to act, they need to be engaged, and that they need to struggle. That’s not a bad thing. That’s the way people learn.

Of course, just because you’re struggling, that’s not a good thing, but the right kind of struggle could lead to the right kind of outcome. The minimalist idea, the way I think of it, is to minimize the extent to which the system and the information get in the way of what the user’s really interested in.

Minimalism Revisited: An Interview with John Carrol

Nicky Bleiel, Intercom February 2013, pp. 7 - 13

When we apply this to a scenario, we would have to ask ourselves what information is needed and what information stands in the way of the what the user is really interested in.

As mentioned in my previous blog, documentation is in my opinion a way of supporting users in reaching their goals. What we can learn from John Carrol is that reaching that goal should be described in an active way - to engage the active user - and limit the amount of content that is not related to reaching the goal.

Writing scenarios

A scenario would then consist of the following steps:

1. Goal setting: what will the user achieve by following the scenario, what goals will be reached?
2. Process: what actions need to be taken to reach the goal?
3. End result: what will the end result look like?

In this way writing a scenario becomes like writing a short process-driven story, with quick lists and actions to guide the active user quickly through complex processes. During the writing process you constantly have to ask yourself what the user tries to achieve and in what way the information helps them reaching their goals. Making an overall process scheme, starting with the goal and then reasoning back to the first process step, is therefor essential when writing process-driven documentation. 

Testing scenarios

Scenarios - like all types of documentation - should be tested by real users. The approach described by Morgan Dennis (2012) for defining test groups and performing scenario tests is a good way of verifying if a scenario really helps users in reaching their goals. I would however focus in my user tests on evaluating if users are able to reach their goals by reading and following the instructions in the scenario, rather than asking them to evaluate the quality of the product and the scenario. Unfortunately in most projects testing documentation is often scheduled after the release of the documentation, so doing some tests with colleagues during the documentation development process is a necessity to have at least an idea of how the documentation will be received. 

During my documentation project for Be Informed, I wrote several scenarios and had them reviewed by my colleagues at the Support desk. As they are answering questions from customers every day, they have a good impression of what kind of questions a user will have.

The downside of process-driven scenarios

So is using process-driven scenarios the solution to all documentation problems? I don't think so:

• There is still the issue of various user groups, reading your scenario with their own goal in mind. Although you can write scenarios specifically for each audience group, it remains hard to help every individual user in reaching their individual goal without adding information that would stand in the way of other users.
• Another issue lies in the serial structure of the scenario. Some users might want to dig deeper into the information, for instance to detailed topics in a reference manual. Minimalism often doesn't offer a complete documentation solution, so we might still need reference manuals to provide users with detailed (function-based) information. The link between a process-driven scenario and reference material is problematic in print-oriented documentation
• In addition the the previous issue, using a serial scenario structure forces users to follow a predesignated path to reaching their goals. This is not a real-life situation. Active users might want to skip process steps or perform them in another order. 

Scenarios offer our users a quick way to learn how to reach their goals. Within the limits of a print-based documentation solution that is the best we can do. But what if we could abandon this traditional approach and use state of the art (semantic) technology to empower our scenarios? Now, that would be a whole different story.

Learn more about this at STC Summit in Atlanta

I will demonstrate how semantic technology can help us in making process-driven documentation accessible at the STC Summit 2013 in Atlanta. 

My session will be on Monday May 6th, 2:00 pm (EDT). 

STC Summit 2013

The STC Summit 2013 is probably the world's largest and most influential conference for everyone working in the area of technical communication. The Summit is packed with more than 80 sessions over the three full workdays with topics covering all aspects of technical writing, editing, project management, and publication production. It takes place 5-8 May in Atlanta, Georgia.

A preliminary overview of the sessions can be found on:
http://summit.stc.org/program-info/program-overview/

Follow me on Twitter 

Make sure to follow @beinformedcom, @cvanmansom and @millsdavis. 

#effectiveinformation

Tweets related to making information accessible by using semantic technologies 

#stc13

All information related to the STC Summit 2013