By, Sheece Baghdadi
I am here to discuss the strategies and mechanics of scenario-based documentation, but before we get to that here’s a tidbit from one of my favorite books that is somewhat relevant.
In Carroll’s, Alice in Wonderland, there is a dialogue between Alice and the Cheshire Cat, which goes like this:
“Alice: Would you tell me, please, which way I ought to go from here?
The Cheshire Cat: That depends a good deal on where you want to get to.
Alice: I don’t much care where.
The Cheshire Cat: Then it doesn’t much matter which way you go.
Alice: …So long as I get somewhere.
The Cheshire Cat: Oh, you’re sure to do that, if only you walk long enough.”
Not unlike the wonderland, there are times where we as writers are not sure which way our users will take. And there are way too many ways to tell them about each and every one of them. So, is it still possible to give our users meaningful documentation and yet not overwhelm them with information?
The answer is a very assertive ‘Yes!’ And scenario-based documentation aims to do just that.
Why & When
Like everything you decide to do, you must ask yourself, ‘why do I want to use scenarios when designing my help content?’ If it is just that you (or your IA, content strategist, or manager) who have decided to add scenarios to all your content (as a process or because it is the culotte that everyone is wearing), you may end up with weak help content. It might seem awesome at first glance but may reveal a lack of understanding of the users’ needs.
A thorough analysis is necessary to understand plausible scenarios. Based on your product, I would recommend you first create 4-5 situations and then enlist the paths the users could take to get there. Now, if this analysis does not result in a couple of scenarios, then I would question if what you are putting together is scenario-based at all. It could mean that there is not much flexibility in how the product works, and the scenario is just regular modus operandi or one amongst a few rigid methods of achieving something.
Usually, when you document a process or a procedure, you present it in the form of step-by-step instructions. If one or two sub-steps are tasks, then those may need to be linked. This can get further complicated if there are many choices, and each choice leads to a different set of steps. In such cases, if you use a scenario instead, you are able to provide your audience a meaningful, substantial, and fluent document. Even if it is not exactly what they want, in today’s age, we can assume they are smart enough, and that someone else’s journey will guide them to their destination.
Choosing Your Scenarios
If you have either created or planned for creating scenario-based content, ask yourself these questions:
- Does it help users understand the big picture?
- Can it serve as a guide to users not using an identical scenario?
- Does the content directly address a large number of users’ needs?
- Does the content help users with the complex bits of the process?
The answer to all questions should, of course, be a Yes. Do notice that the questions don’t pertain to a single scenario, but form a set. You should design your content with the intent of covering most of these aspects with the minimum number of scenarios necessary. Keep the content minimal, flexible, and scalable. Adding too many scenarios will overwhelm and disorient the users apart from bulking up the documentation set.
Scenario-based documentation, when done right, prepares users for working with the product (and does not indulge in hand-holding them through it). Products built on modern technology with an easy-to-use UI will help users to complete the smaller tasks successfully but the end-to-end process would still need assistance. This is the problem that scenario-based documentation approach should intend to solve.
Suggested Outline
When documenting a scenario, here’s an outline that you can use.
| Title/Heading | Contents |
| Description | Give a detailed description of the scenario and what it helps users achieve. Also, mention what features it covers and how it helps users not using the exact same details. |
| Audience | Who should use the scenario. (And who else can use it and take a leaf from it.) |
| Process | This can be a table, a chart or a mini TOC. This is recommended if the scenario is elaborate and contains many steps. This also helps users to directly jump to and view what is relevant to them. |
| Steps | This could be a list of steps or sub-steps. Each step can be separated with a heading if necessary, and if you use this way then do provide a process outline before covering the steps. I recommend not linking out information. If the content is common, you can reuse the information (using snippets or reuse tools). |
| Media | Scenarios are good material for creating a video. If you already have detailed documentation, you could provide a video-only guide of the scenario. Be sure to include voice and captions. |
An Example
In the last few years, one of the technologies that I have been using frequently is the maps feature on my phone or the web. I have used it for calculating distance, traffic, time estimate, bus route, walking route, fastest way and more. It’s a good product to use as an example to describe scenario-based documentation. While the maps product that I use is fairly intuitive, a scenario-based document (or video) is more or less sufficient to help users graduate from a basic to an expert level.
What are the common situations where one would use maps?
- Find a place
- Locate a service (nearest ATM, drug store, movie theater)
- Get directions from one place to another
- Check for traffic on routes
- Share directions
- Find public transport routes
- Distance (Can I walk or use a bicycle?)
- Use voice-based navigations when driving
All of the above or at least most of it can be done on both the web or through a mobile app, so we are spoilt for choices. Now let’s come up with a scenario that can address a large number of these situations.
Scenario description: Driving from location 1 <HauzKhas> to location 2 <Vasant Vihar> using your maps app.
If the above scenario is documented well, it can cover most of the common situations, and would also be a beacon to other situations.
A Graphical Summary
To sum up what is covered in this article, here’s an infographic. (I heart Adioma!)
https://adioma.com/@sheece/infographic/scenario-based-documentation-quickie
About the Author
Sheece Baghdadi is a freelance Content Strategist with a penchant for minimalism. He has over 17 years of experience in the field of user communication and has led Information Development and Globalization teams in the past at BMC Software and IBM.
This article is really helpful at the time of documentation. I usually made a chunk of a large UI and put it in a sequence, for example high, medium, and low. The purpose of mine to follow this process to cover all the possible scenario on the UI. The image in this article is self descriptive, which may be useful for my future work.