Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
Let’s Tell A Story
Scenario-Based Documentation
Once upon a time
there was a doc writer…
• Matt Ness
• Been in the tech writing business for 22 years
• Specialize in Ente...
COLLECT DATA
FROM ANYWHERE
SEARCH
AND ANALYZE
EVERYTHING
GAIN REAL-TIME
OPERATIONAL
INTELLIGENCE
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
Both good....
• “This was a great topic. Very nicely explained with a good example.”
• “Great lay...
https://www.flickr.com/photos/whsimages/897128379/
Once upon a time there was a dark
forest….
What’s in there?
How do I get there?
What should I pack?
Are there
Dark Forest Tutorial
1. Prepare for the forest
a. Pack food in (avoid faerie treats and gingerbread architecture)
b. Bring...
• Detailed historical background
• Table of Dark Forest flora and descriptions
• Bulleted list of Dark Forest fauna
• Note...
• How to steal a leprechaun’s treasure
• How to evade the wiley chupacabra
• How to safely hitch a ride in Baba Yaga’s Hut...
Let’s Go to Grandmother’s House
http://dawnbreakergaming.com/wp-content/uploads/2015/04/woolfe-04.jpg
Step 1: Dress for trip
• Wear special new fire-colored hood and cape
Step 2: Pack basket for trip
• Cakes, pot of butter, ...
Let’s Go to Grandmother’s House
Step 6: Proceed to Whispering Pines Retirement Community
• If you encounter a large talkin...
Kayoshin,
elf ranger/spellcaster
Kristek,
hybrid human/mushroom
fighter (it’s a long story)
GM
a.k.a. “the mysterious,
omn...
Players = End users GMs = Admins /Developers
User Manual Admin Manual / SDK
Modules = Interface to OS
Scenario-Based Docs
Adventures = Scenario-Based Docs
• Users embark on an epic journey (save the world from
destruction!)
• They accomplish am...
Reviews for the adventure “Hoard of the Dragon Queen”
• “The adventure devolves into a series of ‘go fight this, then this...
The world is not enough
Hello Earth!!!
Hi Mars!!! Yo Neptune!!!
Oort Cloud!!
Whassup?!?!
Meanwhile, back in Hong Kong
Slide from a workshop run by sales engineers at our APAC office
Hack Week Draft
Ponydocs Version
“What do you need to do?”
Follow the steps!
Other approaches
Scenario-based doc project
for the IT Service Intelligence
app
Scenario-Based Docs: Best Practices
• Know your customers!
• Develop customer profiles
• Don’t write a tutorial
• Don’t wr...
The End!
• mness@splunk.com
• @moerex on twitter
• #justaxeit
http://dawnbreakergaming.com/wp-content/uploads/2015/04/wool...
Let's Tell A Story: Scenario-Based Documentation
Let's Tell A Story: Scenario-Based Documentation
Let's Tell A Story: Scenario-Based Documentation
Let's Tell A Story: Scenario-Based Documentation
Let's Tell A Story: Scenario-Based Documentation
Let's Tell A Story: Scenario-Based Documentation
Upcoming SlideShare
Loading in …5
×

Let's Tell A Story: Scenario-Based Documentation

1,918 views

Published on

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.

Published in: Technology
  • Be the first to comment

Let's Tell A Story: Scenario-Based Documentation

  1. 1. Let’s Tell A Story Scenario-Based Documentation
  2. 2. 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 software • Sr Technical Writer at Splunk in San Francisco
  3. 3. COLLECT DATA FROM ANYWHERE SEARCH AND ANALYZE EVERYTHING GAIN REAL-TIME OPERATIONAL INTELLIGENCE The Power of Splunk
  4. 4. In Splunk’s early days, documenting was easy Dec 2008: One product, five manuals, plus FAQ and release notes
  5. 5. • Over 50 products, apps, and add-ons • Core product (Splunk Enterprise): 28 manuals Fast forward seven years
  6. 6. We solicit customer feedback Customers also reach us via answers.splunk.com, IRC (#splunk), and other routes
  7. 7. We get customer feedback Both good.... • “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." And bad…. • “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 quick!”
  8. 8. https://www.flickr.com/photos/whsimages/897128379/
  9. 9. Once upon a time there was a dark forest…. What’s in there? How do I get there? What should I pack? Are there
  10. 10. 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
  11. 11. • Detailed historical background • Table of Dark Forest flora and descriptions • Bulleted list of Dark Forest fauna • Notes on important locations • Summary of prominent dangers • Terminology Dark Forest – Conceptual Overview
  12. 12. • 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
  13. 13. Let’s Go to Grandmother’s House http://dawnbreakergaming.com/wp-content/uploads/2015/04/woolfe-04.jpg
  14. 14. 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
  15. 15. 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
  16. 16. Kayoshin, elf ranger/spellcaster Kristek, hybrid human/mushroom fighter (it’s a long story) GM a.k.a. “the mysterious, omnipotent disembodied voice” Xandros the Unsettled, human fighter Brand’r, human mage Karamail, dwarf fighter Not pictured: • Gertie, dwarf cleric • Verdant, human thief (me)
  17. 17. Players = End users GMs = Admins /Developers User Manual Admin Manual / SDK Modules = Interface to OS Scenario-Based Docs
  18. 18. Adventures = Scenario-Based Docs • Users embark on an epic journey (save the world from destruction!) • 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)
  19. 19. 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….
  20. 20. The world is not enough Hello Earth!!! Hi Mars!!! Yo Neptune!!! Oort Cloud!! Whassup?!?!
  21. 21. Meanwhile, back in Hong Kong Slide from a workshop run by sales engineers at our APAC office
  22. 22. Hack Week Draft
  23. 23. Ponydocs Version
  24. 24. “What do you need to do?”
  25. 25. Follow the steps!
  26. 26. Other approaches Scenario-based doc project for the IT Service Intelligence app
  27. 27. 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
  28. 28. The End! • mness@splunk.com • @moerex on twitter • #justaxeit http://dawnbreakergaming.com/wp-content/uploads/2015/04/woolfe-04.jpg

×