Information They Can Really Use

June 18, 2011

My technical writing team recently unveiled Scenario-Based Content, a new documentation strategy that aligns with the same sort of use cases documented as part of an Agile project.

That’s the theory, at least.

My introduction to this new process left me scratching my head. How is scenario-based content different from what we’re already doing?  We’re writing tasks, not concepts, so I had difficulty imagining how I’d apply the new initiative to my work. We had several more presentations and finally, I spoke directly to a writer on a different product who’d already begun using the process.

But it wasn’t until Tom Johnson posted this essay on the failures of topic-based authoring that it all made more sense. As Tom notes:

“The problem with topic-based authoring is that many times, these tasks don’t mean a whole lot in isolation.”

That statement reminded me of my experiences teaching SAP a few years back. When we pilot-tested a course I’d written to teach users how to create product codes in the new system, we discovered all the course did was present a series of isolated tasks, one after the other, with no backbone to tie them all together. Because the SAP system was quite different from the legacy system it replaced, the new tasks did not align perfectly with old ones, so even users’ domain knowledge did not help them. We ended the pilot early and redesigned the course with the end-to-end scenario superstructure Tom describes.

I sat with the students themselves as well as the SAP development team and produced job aids, process flow charts, and various cheat sheets that were essentially a bread-crumb trail through various use cases. For example, the use case for Create a Sellable Product Code is NOT identical to Create a Component Code. Creating a sellable product code required users to perform at least five different SAP tasks, including creating component codes. Worse, those tasks had to be performed in reverse order when compared to the legacy system. The end result was a well-trained user group able to successfully create product codes.

If you’re wondering why I did not design the course this way from the beginning, you’re not alone. The answer? We thought we’d covered that during design. The SAP implementation team consisted of actual business users, yet even they did not consider tying together the tasks required to achieve some goal. Every one believed it would be obvious to users when just the opposite turned out to be true.

This is a problem quite typical on project teams where schedules are aggressive and access to the right experts is scarce. As we adopt our new scenario-based content strategy, I’m concerned the same fate will afflict our documentation.  We don’t always have access to real users and must rely on internal experts from Support, Development and Education.

I’m still not sure how to actually apply our new content strategy but I do think it has the potential for making our information truly usable. What do you think about scenario-based documentation?



  1. I think scenario-based documentation is only as good as the information you get about the scenarios and the actual product. The scenarios may leave a lot of holes in what the users need to know about using the product. I don’t think even a very skilled writer can write useful documentation for users without learning how users will actually apply the product, or without hands-on experience with the working product. If the parts being developed piecemeal in an agile development plan don’t work together yet, it would be like documenting “vapor ware.” In my opinion, it could be a worst-case scenario.

    I also think that user scenarios are analogous to personas in specifications. I worked for a start up that was developing an online system for buying and selling TV commercials. They had a great cast of personas for the ad buyers, the advertising agencies,and the network and local station sales forces. In 2 years they developed an impressive web site. However, they overlooked a few other important requirements. When the system had as few as a dozen simultaneous transactions, it crashed. No one had considered transaction volume when they created the initial specs. They had to go back and spend another year redesigning the whole system to handle a more realistic transaction volume. I think scenarios, like personas, may not show you the whole system.

  2. After I initially commented I appear to have clicked on the -Notify me when new comments are added- checkbox and now every time a
    comment is added I receive 4 emails with the same comment.
    Is there a means you are able to remove me from that service?
    Thanks a lot!

  3. Thanks for the good writeup. It in reality was a entertainment account it.
    Glance advanced to far brought agreeable from you!
    However, how can we communicate?

  4. Thanks for sharing your thoughts on cannabis. Regards

  5. Hi terrific blog! Does running a blog similar to this take a large amount of work?
    I’ve absolutely no expertise in programming but I was hoping to start my own blog soon. Anyway, should you have any ideas or techniques for new blog owners please share. I know this is off subject however I just needed to ask. Thank you!

  6. Very quickly this site will be famous among all blog people, due to it’s fastidious content

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 )

Google+ photo

You are commenting using your Google+ 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 )


Connecting to %s

%d bloggers like this: