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 Enterprise and Data Analytics

software• Sr Technical Writer at Splunk in San Francisco

COLLECT DATA FROM ANYWHERE

SEARCHAND 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 feedbackBoth 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!”

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 monsters?

Dark Forest Tutorial1. 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 foresta. South of Mount Doomb. Turn left at Shrek’s Castle

3. Enter the foresta. Stay on the path! b. Leave an offering for the Queen of the Wood, for this is her hunting ground

4. Spend the nighta. If there are goblinsb. If there are giant spidersc. 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• Terminology

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

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, cash, mace• Ultrasharp, 8 X folded Hanzo steel woodcutter’s axe

Step 3: Enter the Dark ForestStep 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 HouseStep 6: Proceed to Whispering Pines Retirement Community

• If you encounter a large talking wolf: AXE IT A QUESTIONStep 7: Locate Grandmother’s House

• Avoid houses containing unusually furry residentsStep 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

Kayoshin, elf ranger/spellcaster

Kristek, hybrid human/mushroom fighter (it’s a long story)

GMa.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)

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 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

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 projectfor the IT Service Intelligenceapp

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

The End!

• mness@splunk.com• @moerex on twitter• #justaxeit

http://dawnbreakergaming.com/wp-content/uploads/2015/04/woolfe-04.jpg