Technical Writing Vs. Narrative Fiction, Part 2

Telling a Story

Chapter 3 – Configuring Disaster Recovery for Zombies

Disaster recovery is a system configuration that helps ensure your network environment remains secure and online in the case of a physical catastrophe; for example:

• Earthquakes
• Hurricanes
• Zombies

How Disaster Recovery Works
When the primary system on which the software is installed goes offline (when zombies chew through the wires or set the building on fire), failover is initiated, and the secondary system is automatically brought online at another location (Alaska, where there are no zombies…yet!) and continues to function with a minimum of downtime.

This chapter describes the procedures necessary to configure disaster recovery in your infrastructure and fend for your life from flesh-eating zombies, including:

• Installing the software
• Killing zombies: guidelines and best practices
• Configuring disaster recovery

To install the software
1. Log on to the server system as the administrator.
2. Navigate to the closest exit.
3. Double-click……Zombies!

A software user's guide tells a story (sans zombies). A novel tells a story (about anything, including zombies). It could be argued (I double dare you) that any book, technical or otherwise, has to tell a story. What kind of story does a software user guide tell? Well, in the planning phase of my disaster recovery user guide (my example from Part 1 all the way through here) I have to determine who my audience is so I have a better understanding of what they need to know about disaster recovery. Is the user very technical? If not, I will need to include more introductory and concept material. Is the user a network administrator? If so, my user won’t need a lot of setup, she will just need the procedures to configure her software for disaster recovery.

Where’s the story in that? Well, look at the outline. Chapter 1: Introduction. Chapter 2: Install and Configure software. That’s for the new user. The experienced user does not need as much intro material, so that will not be part of the story. What is the motivation? Why tell this story? My audience, new or experienced, needs to install and configure the software correctly. I have to tell the story of this install and configuration.

During my planning phase, I’ll determine how I will tell the story. There are two ways I can go:

• Start with the easiest information and then, continuing through each chapter, get more and more detailed, more technical. This might be the way I write one user guide for both those audiences (new and experienced). The new user will get all she needs in the first few chapters and then can stop reading. The experienced user might skip the early chapters, and get to the nitty gritty of the story: the procedures she needs to configure the software for every disaster recovery scenario (there is more than one type of failover—but I digress).

• Tell a story from start to finish, logically, like documenting each point of a flowchart. Maybe every user needs all the information, so chapter 1 begins my story from where any user needs to start the process. Chapter 2 continues it, and so on, through to the last chapter. You can look at the table of contents of my user guide and consider each chapter as one process in a complete series of necessary processes (Chapter 1=Process 1, Chapter 2=Process 2), with each chapter/process broken into all the procedures needed to complete the process.

No one, and I mean absolutely no one, reads a technical document for fun. (Unless you’re a technical writer studying bad tech writing to figure out what not to do.) But many people, whether they’re an engineer (learning a new product or reviewing technical documentation because they’re the only person in the world who knows how a piece of the software puzzle works because they wrote the code) or a soccer mom (installing the latest version of iTunes) will at some point have to read a user guide or some online help topics. The more concisely you present and tell the story, the better experience any user will have with her product. Often a user clicks that Help button because she can’t do something. She needs information fast; she’s pissed off, and she’d rather not call tech support. This is when telling that story about the installation and configuration saves the day.

It should go without saying that narrative fiction also tells a story. I mean, that’s why it’s narrative; it tells a story, somehow, from start to finish. But how are these two types of storytelling similar? Okay, you’re in a book store and you pick up a copy of the new hardcover by that hot young author who looks good in heels and has a haircut you envy. You’ve heard good things, read decent to excellent reviews, and you need to find out for yourself. You read the first paragraph. It doesn’t grab you. You read two pages; you’re still not sold. One more page, and the hot young author has lost you. You put the book down, walk away, and buy a new book by a writer whose ten other books sit happily read on your bedroom bookshelf (yes, I have a bookshelf in my bedroom).

What the hell just happened? This reader clicked Help and tried to determine what the story was. And she either had no idea what the author was trying to say, or it wasn’t for her. She may or may not know why. I’ll argue that a reader of a user guide can get the same feeling—this book sucks, but why? In both cases, the story failed. For the fiction reader (reader A) the author failed at storytelling. But, we can assume that if it didn’t work for reader A, there’s a reader B and C for whom it didn’t work equally well. She is not alone.

Novels and user’s guides must tell a story clearly, concisely, and with a minimum of bullshit, or readers will give up out of frustration. Which brings us to the most important part of this comparison: Editing.

Tune in next time when I’ll discuss the following parts of editing:
• Structure
• Pacing
• Consistency
• Standards