To new users, complex software products can seem like dark woods on a stormy day. As tech writers, we often spend a lot of time talking about the overall shape of the forest and the variety of paths within it (conceptual docs), creating detailed catalogs of local tree species (reference docs), and providing step-by-step guides to things like “how to cross a river” or “how to knock on a door” (task-based docs).
But none of that helps your customers when they just want to know how to get to Grandmother’s house, without getting lost in the forest, falling into the river, and accidentally going to the other cabin in the woods, where the lycanthropic senior citizens live.
In other words, your customers need a narrative. And maybe they need lots of them. When you’re dealing with products that can be run and configured in a bewildering variety of ways, a single getting started manual might not do the trick. It’s like giving people a Choose Your Own Adventure book and only allowing them to choose one path through to the end.
For my talk I’ll explain how we became aware of the need for better scenario-based documentation, and how we ended up building a prototype during a hack week project. Now we’re on our way to creating a collection of short stories that show users how to string sets of features and procedures together to solve complex problems. We’ll cover some of the things we’ve learned along the way and offer best practices for those who want to tell a few stories of their own.
Matt Ness is a technical writer with over twenty years of experience at places like PeopleSoft, Oracle, and Intuit. He's currently a writer for Splunk, a leader in the machine data analytics sector.
Hi, I’m Matt I’ve been working as a tech writer for a couple decades now, mostly in the field of enterprise and data analytics software. I’ve been a writer with Splunk for almost 7 years now, which is a strange thing to say. It doesn’t feel like I’ve been there that long. Splunk is a fun place to work. You’ll find out one reason why I say that about halfway through this talk.
So, just for some context, here’s what Splunk is all about. I’m gonna go all corporate on you for a minute.
At it’s core, the Splunk platform enables you to:
Collect data from anywhere – with universal forwarding and indexing technology. Search and analyze across all your data – with powerful search and schema-on-the-fly technology. Rapidly deliver real-time insights from machine data to IT and business people – through a powerful UI and dashboards.
This is what we call Operational Intelligence.
Alright, back to our scheduled program.
I joined Splunk in 2008. (CLICK) Back then our documentation set was relatively easy for us writers to manage, and for our customers to apprehend.
Back then we had just one product—it was called Splunk.
The documentation for that product was broken out into just a few manuals, all broken out by role or task.
Stuff was (relatively) easy to find!
At that time, the bulk of our customers were technically sophisticated problem solvers. They were the kind of people who Knew their way around regular expressions and could tell their TCP inputs from their UDP inputs They loved the challenge of learning and mastering a sophisticated search language. They’re the sort of folks who now relax by hanging out on our IRC channel (hashtag Splunk) and our Answers site, helping newbies with their Splunk-related quandaries Sometimes we hire them.
Seven years later, things have changed
We now have customers who aren’t as patient as those early adopters They’re not always as technically sophisticated Or have the time or inclination to puzzle out solutions They want complex problems to be solved YESTERDAY Our tutorials get them started but don’t always take them where they need to go
Meanwhile our documentation options have expanded, as we’ve introduced more products and more manuals There are more moving parts, more things to fit together More docs to read A much wider range of functionality and problem-solving capability, if people know it’s there and how to use it
At Splunk we have a lot of communication with our customers.
Every topic has a feedback form and an option to leave comments, and we try to respond to all of them. Customers also communicate with us through IRC, and our Answers community And we get customer input from our support, sales, and professional services divisions
From day to day most of our comments are suggestions for doc improvement. (CLICK)
Occasionally we get praise. (CLICK)
And sometimes people throw rotten tomatoes at us.
A lot of the pointedly negative feedback relates to the plethora of manuals, number of topic-to-topic links, and amount of reading that must be done Others just want simple instructions for complex tasks: I want to do the thing! Show me how to do the thing! Please tell me, this thing it must be done!
We can get people started with a tutorial but it’s obvious: we have a chasm that must be bridged
Something that will help us get users from beginner to intermediate, or from intermediate to expert. Something that will connect the dots.
For new users, getting started with a large enterprise application is like taking a journey into a dark, enchanted forest. (CLICK through)
There are quests that they want to take, but they do not see clearly how to complete them.
So, how do we get them started? How do we give them a way forward that puts them at ease and routes them around the obvious pitfalls? How do we help them accomplish their objectives?
And what do we do to help them not just become familiar with the forest, but expert travellers within it?
You could give them a tutorial, something that helps them become entry-level Dark Forest explorers. A sort of “Hello Forest” exercise. They’ll learn the basic prereqs, find out how to access the forest, and maybe do a quick camping trip overnight to get a feel for the place.
It’s good, for a start. But it doesn’t do much more than get people familiar with the basics. If they want to do something truly useful—like consult with the Lady of the Lake, or successfully capture a Firebird, they need more help.
You could provide your customers a conceptual overview of the Dark Forest. Give the forest user some historical context, and provide a general idea of the stuff they’ll find in the forest. You could even include some cool diagrams that provide a big picture view of how the forest operates. Maybe it’s powered by the magic of a unicorn, or maintained and protected by a collective of sentient trees.
Make sure to provide lots of links to more detailed information, of course.
Alternatively you could provide procedural information—lots and lots of task-oriented topics that cover all of the different kinds of things that an experienced Dark Forest explorer should know how to do. A different procedure for every possible thing one might want to do in the forest. If you provide a decent table of contents and index, they should be able to piece together the various things they need to do to carry out whatever quest they want to carry out. Right?
But these solutions aren’t always super helpful for users who need to make the leap from spending a night near the border of the forest to doing something that is actually significant.
The conceptual overview is too broad, and the procedures are too detailed, and many of them are irrelevant to what some forest explorers need to do.
This is where a scenario-based or use-cased based walkthrough can come in handy. (CLICK)
Let’s say you have a customer named Scarlet. She’s got a delivery to make. She wouldn’t ordinarily have to do this, but her younger cousin went in without much prep, and is now missing. Scarlet needs help getting to a small senior citizens community that is mysteriously located in one of the more treacherous parts of the Wood. Can you help her out? Sure you can.
So here’s where you come up with a way to tell an instructional story that brings the customer to the ending they want. Not the one where they find themselves in the belly of a wolf wearing an old lady dress. But the one where they are victorious.
It’s similar to the tutorial, but it goes further. It knows who it is talking to and what they want to do.
It provides useful prereqs that are specific to the task at hand.
It assumes that certain basic knowledge—such as how to find and enter the Forest—is known.
And it provides useful tips and tricks to get them through their journey with a minimum of distress.
Most importantly it takes into account some of the more…threatening variables that might trip up the customer, and it tells the customer how to minimize or defuse their menace.
The point is to show your customer how to get a complex task done, in a way that might help them take on similar tasks in the future with a minimum of confusion.
Now, all this talk about axe combat with werewolves in weird enchanted forests full of fairy-tale creatures is reminding me of something that’s kinda relevant to our topic. (CLICK)
Ah. There it is. Tabletop role-playing games. Dungeons and Dragons. Now, I’m willing to bet that the majority of people attending this talk either know what I’m talking about from direct experience or know people who do. A number of you are either self-identifying nerds or are “nerd adjacent.” That’s how Ann Wheaton, wife of Wil, describes herself.
Storytelling – and getting people through it to the end – is at the heart of D&D. For those who are unfamiliar with the dynamics of D&D, it boils down to this: you have a set of players and a game master. The game master tells the players what they see. The players tell the GM what they do. And the GM tells them what happens. Dice are rolled to determine the outcome of certain actions and events.
If the game master is doing their job and the players are sufficiently focused, everyone gets swept up in the adventure—sometimes legendary, sometimes ludicrous, always fun. Neither party knows exactly what will happen next until it’s all over.
Along the way, ridiculous things are said, and hopefully people remember to write them down. (CLICK, pause for laffs)
So I came back to D&D a few years ago after a hiatus of several decades. I played the game through much of middle school and high school—this was back in the early 80s, when the only types of D&D available were called “Basic” and “Advanced.” It was still a pretty new thing. Then I went to college, where I made friends who were more interested in deconstructing French New Wave Cinema and debating postmodern theory than role-playing games, and it became a thing of the past.
Two decades and change later, I joined Splunk. Rachel, my boss at the time, played D&D and was thinking about getting a an office game going. When she asked me if I’d like to join, I said sure. That was around 2009 and our little group is still going. Turns out: D&D goes well with scotch whiskey. Who knew?
Here’s the gang I play with at Splunk. By day, they’re the best of the best of our product development, support, business development, professional services, and sustaining engineering teams. Every other Wednesday night, however, they become…(CLICK) someone else. We order delivery food, sometimes someone brings some nice wine, and we stay late at the office rolling dice, chasing slave merchants through ancient subterranean minotaur cities, and slaying terrible beasties.
It’s a good time.
So, the interesting thing about D&D, as well as just about all other decent table-top roleplaying games on the market, is that it is heavily documented. There are a lot of rules and tables and charts and stats and types and classes of things—all the stuff you need to build and operate a fictional world that works with playable mechanics.
Some people are frightened away by all this text.
But as a kid, I was drawn to it. This is the book that sold me on the game way back in 1982. A whole manual of monsters. What could be greater? I spent hours poring over all of the monster descriptions and stats. Some of them I memorized. Carrion crawlers. Owlbears. Intellect devourers. Gelatinous cubes. Chromatic dragons. The dreaded beholder!
So there you have it—I was fetishizing a manual—documentation—when I was in middle school. Suddenly my choice of career path makes sense.
So, just like software, new versions of D&D are released every few years. With every version, they put out a new set of manuals, with updated rules, adjustments to gameplay, and new art.
The 5th edition of Dungeons and Dragons was released last year, to mostly positive reviews.
Here’s what the Monster Manual looks like now. The art and book design is a lot cleaner nowadays, for better or worse, depending on your preference. Personally, I love that updated beholder on the book cover. But I know a several people who will always prefer the relatively crude sketches of yesteryear.
So in software documentation terms—I see the Players Handbook as the User Manual. This is where people go to get the ground rules for the game’s operating system. It’s where they learn how to create their characters, and it teaches players how to handle basic adventuring things--buying supplies, combat with weapons, learning skills, acquiring and casting spells, and so on. It gets both players and game masters started. (CLICK)
The Dungeon Master’s Guide is for game masters only. It’s an administrator’s manual. It tells game masters how to run a game that moves well and is fun for the players. It also functions as an SDK. There’s a great deal of material to aid game masters and adventure developers in the creation of imaginary worlds and the adventures that take place in them. (CLICK)
The adventures—or “modules” in D&D parlance--are where everything comes together—because without the adventures there’s no game. They’re the story that the game master tells, the environment that the players move within and make their decisions. The adventure is all scenario-based documentation. The only difference here is that this documentation is transmitted to the end users through the admin, who keeps the details a secret—the game master has the map, the players need to discover it and defeat the creatures, traps, and plot developments between them and their goal.
But at the end of the day the mission of a D&D adventure shares many of the same goals as scenario-based documentation:(CLICK)
They want to get the end users from start of an adventure story to its satisfying conclusion.(CLICK) They help the end users accomplish a few amazing feats along the way.(CLICK) And ideally the process of engaging in and completing the adventure ensures that the users “level up” at the end, so that they complete the experience stronger and with more confidence than they had when they went in.
Just to make sure this doesn’t sound too much like a clever buzz marketing campaign for Wizards of the Coast, the company that publishes D&D, let’s talk about what happens when things go wrong with their products. D&D pretty much lives and dies by how playable it is. Over the years the ruleset has undergone several major revisions. When I came back to the game a few years back they were on the 4th edition, which was considerably more complicated than the version I’d played as a teen.
The 5th edition of D&D scaled back the rules to make the game more approachable for new users, and to make gameplay move faster. Overall it looks like the 5th edition is well received, but that doesn’t mean that Wizards of the Coast isn’t making missteps. Their first big adventures for the new edition were panned by critics. The culprit? (CLICK)
Bad writing. Obvious and unimaginative adventure workflow. Maps that weren’t correctly labeled. And a whole bunch of material that somehow failed to get into the printed book, so they offered it as a downloadable .pdf instead. A lot of things that could have been corrected by a more detail-oriented team of writers, who were perhaps given a little more time to deliver their product.
Sound familiar to anyone?
In in tabletop role-playing games like D&D there’s a concept called “railroading.” Part of the fun of these games is that the players theoretically have absolute free will. For example, there’s technically usually nothing really stopping a group of players from quitting a dungeon crawl, going topside, and setting up a crepe shop in a nearby village, if that’s what they really want to do.
This is where a game master sets up all kinds of devices to push players through an adventure, all to keep them on the One True Path. They can create maps that appear to allow players to go in a variety of directions, but in reality provide only one way to get from point A to point E. “Oh you want to go to the next town instead of the Griffon Keep? Go ahead! Oh too bad, the bridge to that town was washed out by a storm.”
Or they might have a whole host of non-player characters—village innkeepers, town mayors, stray knights--constantly remind the players that they need to continue the obvious mission when they seem to be stalled out somewhere or (worse) going in the wrong direction.
Railroading is controversial. When it’s really obvious it can make for a dull game—nobody enjoys feeling like a puppet. On the other hand, plotless stories are lame as well. So the trick is to come up with stories that are worth going on a railroad for.
This is also true for scenario-based documentation, especially if you’re documenting a product that is wide open in the range of choices it gives its users. If your product has a UI component, and its UX team is good, they may be able to mitigate a certain amount of customer confusion that comes with huge feature sets, endless configurability, and somewhat free-form task workflows.
Either way, you’ll still want to document some well-defined use cases for your customers to help them down their road.
Get to know your customers well enough to find out where they want to go and what they need to do. Then take them there on an express train to Awesometown, otherwise known as THAT PERFECT SOLUTION TO THEIR TRULY VEXING PROBLEM.
Unlike D&D players, your customers aren’t expecting surprises and would rather not run into them. They won’t mind the railroad experience, especially if they learn something new along the way.
So, as we come back on our side of the looking glass and return to the subject of documenting technology products, I’d just like to reiterate that scenario-based documentation is for customers who have finished the tutorial and now want to get something real done. The tutorial did its job. It got them to a simple HELLO WORLD state with your product. (CLICK)
Now you need to give them some scenario-based documentation to get them where they really want to go: the offworld colonies. (CLICK)
They want a hello Mars (CLICK), hello Neptune (CLICK) or even (CLICK-CLICK) Hello Oort Cloud experience. And you can give it to them.
The Splunk documentation organization was aware that there was a need for some kind of large-scale scenario-based material. While we spent our time just trying to keep up with the pace of development, documenting new functionality and birthing new manuals to contain that documentation, we had people in our professional services and sales engineering divisions taking our documentation debt into their own hands, designing and writing use-case-oriented educational material to bridge the documentation gap between novice user and expert.
In October of last year my coworker Robin Pille and I had our attention drawn to a presentation for Splunk Enterprise, our core product. It was created by the sales engineering organization at our Hong Kong office. It led customers through the process of creating a dashboard that displayed data about password hacking attempts on a web server. It covered a variety of subjects—extraction of fields from log data, construction of the necessary search strings, creation of a dashboard with different types of data visualizations, and hacking into the XML behind the dashboard to add specific drilldown mechanics.
This project brings together functionality that is currently spread across six or seven manuals. If a user tried to figure out how to put this project together on their own, they would have to read through large portions of those manuals and do a lot of trial and error to get it right. Some people are up to that challenge. But a lot of people aren’t.
In other words, it was just the thing we were looking for. The Splunk development organization was gearing up for a big hack week event, and we decided to make this our contribution. We were the first doc team in the history of Splunk to participate in a hack week event. It was a lot of fun.
For the hack week draft, we threw the project together in Google Sites, partly to get the feel of a different docs solution than the one we typically used, and partly because it could do a few things that our current docs solution can’t, at least at the moment, like display video.
The target audience for this is the sort of user I’ve been talking about all along—someone who has basic familiarity with the product, and who is now trying to get over that hump from beginner to intermediate, or from intermediate to expert.
I liked being able to put note information in the sidebars along the right side of the page.
When we were finished, the project was a hit—we received praise not only from our managers, but also upper management in development and marketing.
Next, we moved our scenario-based doc project to Ponydocs, our home-brewed open-source Media-wiki-based documentation system.
It now looks cleaner, and like part of our docs set. The right-hand sidbar notes had to be added into the main text body of the scenario stages, but we hope to get them back in a future update of the Ponydocs UI.
The scenario starts by clarifying the use case at hand and listing the goals of the project—the things that the user needs to complete to resolve the use case.
This Goals section also includes a big-picture summary of the stages involved in getting to those goals, and a list of the prerequisites that must be completed before they can start. In this case, the main prereq is the indexing of the sample data that this scenario depends upon.
We created a video that quickly demonstrates the end goal, which in this case is the dashboard that the users are to build. The video does not waste any time explaining how the dashboard gets built.
We broke down each stage of the project into easily digestible groups of procedures, breaking down some of the cognitive leaps a user needs to make in order to solve this problem.
And yes, this an obvious railroad. But we are confident that it is a track the user won’t mind following.
This particular stage of our scenario—titled “Examine your data”-- contains two procedures. One where the user reviews event patterns in the data and finds a pattern that fits the type of events they want to search on, and another where the user runs a search using the event pattern that they have isolated. When they’re done, they’ll go to the next stage of the scenario, where they learn how to extract fields from the events returned by that search, fields that they’ll need for their dashboard visualizations.
Ideally users will return to certain scenario stages to get inspiration for solutions to similar problems they may be facing as they use the product.
Other writers at Splunk are beginning with their own approaches to scenario-based documentation.
Writers for our apps team deal with product offerings that do not always involve the broad range of functionality covered by the core product. But they’re still trying to help our users with use cases that aren’t easily sorted out by just “reading the manual.”
This use case scenario shows the user how to build a solution for an online marketplace that needs to maintain its service level agreements. The marketplace has guaranteed that their site will be available 99.9% of the time, which which translates into a maximum allowable downtime of 43.2 minutes per month. This document shows the user how to create a service that monitors the site for problems that could lead to a service failure, sends alerts when failure conditions occur, and identifies root cause so problems can be solved quickly.
So what have we at Splunk learned while working on these projects? (CLICK)
First off, know your customers. Know what problems they’re trying to solve. Find out what roadblocks are they running into as they stumble around trying to solve these problems on their own. If you don’t know, talk to people at your organization who have regular customer contact: support, sales, professional services, education services.
Develop customer profiles and pitch the scenario to a specific profile. This can cut down the scope of the scenario and its solution.
This isn’t a tutorial. This isn’t about getting started, it’s about what to do after you’ve gotten started. It’s about solving big problems.
This isn’t a marketing case study. Marketing folks sometimes promise customers the moon. If that’s what they’re doing, then this is where you show them exactly how they DO get to the moon. Prove your product can do what Marketing says it does.
Try to keep it as simple as possible. This is why chunking information into separate, easily digestible topics can be a good idea. The longer the topic, the more overwhelmed the customer is likely to feel. Don’t waste time explaining how things work under the hood if you don’t need to—provide informational links out to the primary docset for that sort of thing.
If you can use video, use it sparingly, strategically, and as a supplement to the text—video should always be used for illustration rather than documentation. And keep your videos short—we kept ours down to 30 seconds on average. Customers should not need to watch video to learn how to do a thing.
And finally, building these things can be fun. They allow you to see the product through a specific customer’s eyes. In the process you sometimes discover new ways to write about your subject that you hadn’t before. You’re telling a cool adventure story, and it gives the customer a Hollywood ending every time. What’s better than that?
And that’s it, folks! If you have any questions, feel free to ask me when I’m down on the floor.
Let's Tell A Story: Scenario-Based Documentation
Let’s Tell A Story
Once upon a time
there was a doc writer…
• Matt Ness
• Been in the tech writing business for 22 years
• Specialize in Enterprise and Data Analytics
• Sr Technical Writer at Splunk in San Francisco
The Power of Splunk
In Splunk’s early days, documenting was easy
Dec 2008: One product, five manuals, plus FAQ and release notes
• Over 50 products, apps, and add-ons
• Core product (Splunk Enterprise): 28 manuals
Fast forward seven years
We solicit customer feedback
Customers also reach us via answers.splunk.com, IRC
(#splunk), and other routes
We get customer feedback
• “This was a great topic. Very nicely explained with a good example.”
• “Great layout and navigation, and a lack of ‘filler’ words (yay!)”
• "I'm impressed by the documentation's organization, liberal use of explanatory
links, concise statement of operation, its consistent and pleasing visual format
and use of examples without being obtrusive."
• “I feel like the site is an awful mess of links.”
• “Too many manuals which are wordy and say a lot without saying anything. ”
• “Why don't you provide a simple and clear example for forwarding data with Universal
Forwarder for a Linux Syslog.... why does it take me hours and hours to look that stuff
up. You have a very complex software, but most people do need the SIMPLE stuff
Once upon a time there was a dark
What’s in there?
How do I get there?
What should I pack?
Dark Forest Tutorial
1. Prepare for the forest
a. Pack food in (avoid faerie treats and gingerbread architecture)
b. Bring appropriate charms, wards, and weapons. Wear layers
2. Find the forest
a. South of Mount Doom
b. Turn left at Shrek’s Castle
3. Enter the forest
a. Stay on the path!
b. Leave an offering for the Queen of the Wood, for this is her hunting ground
4. Spend the night
a. If there are goblins
b. If there are giant spiders
c. If you hear your name called from the treetops in a whispering singsong
5. Leave the forest
a. Exits may be further away than they appear
• Detailed historical background
• Table of Dark Forest flora and descriptions
• Bulleted list of Dark Forest fauna
• Notes on important locations
• Summary of prominent dangers
Dark Forest – Conceptual Overview
• How to steal a leprechaun’s treasure
• How to evade the wiley chupacabra
• How to safely hitch a ride in Baba Yaga’s Hut
• How to catch the mysterious Questing Beast
• How to climb the Giving Tree (free apples!)
• Etc., etc., etc.
Dark Forest – Procedural Docs
Let’s Go to Grandmother’s House
Step 1: Dress for trip
• Wear special new fire-colored hood and cape
Step 2: Pack basket for trip
• Cakes, pot of butter, cash, mace
• Ultrasharp, 8 X folded Hanzo steel woodcutter’s axe
Step 3: Enter the Dark Forest
Step 4: Hire protection from local woodcutters (optional)
Step 5: Cross bridge over the Rushing River
• Do not feed troll under bridge
• Even when he makes ad-hominem attacks
Let’s Go to Grandmother’s House
Let’s Go to Grandmother’s House
Step 6: Proceed to Whispering Pines Retirement Community
• If you encounter a large talking wolf: AXE IT A QUESTION
Step 7: Locate Grandmother’s House
• Avoid houses containing unusually furry residents
Step 8: Knock on door
• If granny seems overly hairy, ears large, sharp teeth, etc: AXE IT
• If grandmother is indeed grandmother, greet her & get inside
Step 9: Eat cake with butter and enjoy Grandma’s company
• And again, if a wolf comes calling: JUST AXE IT
• Or trap it in a sack and drown it in the lake
• Your choice
fighter (it’s a long story)
a.k.a. “the mysterious,
Xandros the Unsettled,
Karamail, dwarf fighter
• Gertie, dwarf cleric
• Verdant, human thief (me)
Players = End users GMs = Admins /Developers
User Manual Admin Manual / SDK
Modules = Interface to OS
Adventures = Scenario-Based Docs
• Users embark on an epic journey (save the world from
• They accomplish amazing feats (slay dragons, destroy demons,
free the people)
• And hopefully level up (better powers, cool new spells, more hit
points, keys to the city granted by thankful lord protectors)
Reviews for the adventure “Hoard of the Dragon Queen”
• “The adventure devolves into a series of ‘go fight this, then this and then this.’
There isn't much room for choice.”
• “The editing is TERRIBLE. It completely ruins the product. (Almost?) Every map has
omissions, or lacks keys or descriptions. Monsters are listed as being in two
different places at once.”
• “First off, most of the important information required for running this has to be
found online. It's not even in the Monster Manual or the Dungeon Master's Guide.
So download it and then...never ever lose that file?”
Bad RPG writing = Bad RPG experience
D&D Players have feedback too….
The world is not enough
Hi Mars!!! Yo Neptune!!!
Meanwhile, back in Hong Kong
Slide from a workshop run by sales engineers at our APAC office
Scenario-based doc project
for the IT Service Intelligence
Scenario-Based Docs: Best Practices
• Know your customers!
• Develop customer profiles
• Don’t write a tutorial
• Don’t write a Marketing case study
• Simple procedures for a complex process
• Use video strategically and as a supplement ; keep it short
• Have fun with it
• @moerex on twitter