Narration in Technical Writing 1

Posted on November 18, 2013


Every tech writer has a literary giant hiding inside. Why wait? You can use that talent for narrative at work.

The Movie Trailer Intro

I have been very fortunate to work with many brilliant people in my career. The year before last, my friend Mark Hoffman and I were the primary authors on a paper that took top honors at Think Week.  I can tell you about it now because not only did Microsoft make the paper public, they also put my name on it. There is something else I can tell you now too: We cheated.

A little history on Think Week, from Mr. Gates himself:

“Right now, I’m getting ready for Think Week. In May, I’ll go off for a week and read 100 or more papers from Microsoft employees that examine issues related to the company and the future of technology. I’ve been doing this for over 12 years. It used to be an all-paper process in which I was the only one doing the reading and commenting. Today the whole process is digital and open to the entire company.”

-Bill Gates

I’d worked on other papers for Think Week before, frankly more astounding and ground-breaking stuff, if you think meta-languages are uber sexy stuff, which sadly, I do. But I didn’t cheat and so a brilliant idea was probably passed over. Now a typical Microsoft whitepaper template might start off something like:

Executive Summary

Borrrring! I mean I wrote the stuff almost every day and I still had a hard time parsing what went where, which makes sense if you are saying the same thing three times over before you get off the second page. In fact, I wonder how many of those papers Bill even gets to the second page on?  So here you have a couple of guys,  one an aspiring author (aren’t we all), one in the Blues Hall of Fame for his seminal book on Howlin’ Wolf, and here we are cramming the work of some of the brightest people on earth into this stilted format.  But boy, were we good at it. Fortunately at the time I was lucky to be working with another brilliant architect/writer, Paul Slater, who taught me a trick – the movie trailer opening.

All of these years in technical writing we have been breaking the cardinal rule of good story telling:

Show, don’t tell.

By endless telling and never showing. Going on and on about what software will do. Who cares? The question is:

What will your software do for me?

And honestly, if you can’t answer that, if you don’t spend a good chunk of time with that, then you don’t know enough to start your project anyway.

So instead, we wrote this as the intro:

Imagine that you’re working in Macau for six months, and your wife has
come to visit you.come to visit you. Several weeks before her visit, you joined an online social
environment that alerts you whenever any groups in that environment form
to alert you of events and topics near you that might interest you, such as
Macanese folk-pop concerts, sailing events, and natural disasters.
This morning, you left for work just as your wife left to play golf with a friend
on Coloane Island to the south. At 9:37 a.m., the building where you work in
central Macau starts to shake violently. You run outside and see hundreds of
other workers from surrounding buildings. You try several times to call your
wife’s smart phone but can’t get through. Then you receive a text message
on your smart phone that asks if you want to join a group in the social
environment called “Macau earthquake group,” or MEG for short. You click a
link on the text message, enter your credentials for the social environment,
and see on your smart phone the home page for MEG. It’s fully configured for
an emergency and includes a link to the Global Disaster Alert and
Coordination System web site ( complemented with
suggestions about what to do during and after a major earthquake, along
with emergency organizations and rescue locations in and near Macau. It
displays a button that says, “Tell your family and friends you’re safe.” You
press the button and see a pre-written message that says, “I’m OK. How
about you?” It shows your current location in latitude and longitude. You
recall that when you subscribed to “natural disasters near me” groups in the
social environment, you provided a list of contacts such as your wife and
children plus their phone numbers to whom you could send such a message.
You make minor edits to the message and press “Send.” Other pages linked
from MEG’s home page include news feeds from earthquake experts
worldwide, text messages from eyewitnesses all over Macau, and even a few
photos and video clips of the earthquake from eyewitnesses. Along the
bottom of a map of the Macau region, you see scrolling text updates about
the quake and feeds from local governmental and volunteer agencies that
provide information about shelters and aid services. The continuously
updating Macau map on your smart phone shows that most of the roads and
bridges in Macau and Coloane are damaged. You see short, Twitter-like
messages from people who joined MEG, and you send one of your own to say
you’re safe outside your building. You also see tweets with hashtags
#eqinmacau and #eqinmacauneedhelp that offer links to important
resources. Some of your coworkers and Macau friends also joined MEG. You
see several of them tagged in the onscreen map of Macau, but you don’t see
your wife. After you send her another text message, you’re delighted to see
her texting back. She’s OK. She read your “I’m OK” message and your text
messages. She’s still near the golf course on Coloane, and she just clicked a
link in your “I’m OK” message to an invitation to join the Macau earthquake
group. A minute later her icon appears on the group’s map.
At 9:57 A.M., you receive a text message that a tsunami is heading toward
Macau and will hit the region at about 10:30 A.M. You zoom in on the Macau
map on your smart phone, and it shows where the tsunami might reach in
various scenarios, from best-case to worst. The golf course on Coloane is
inundated in every scenario. Your wife is in the path of imminent death. You
text her again and tell her to get out of Coloane or, if she can’t do that, head
to high ground. She texts you back that she knows about the tsunami; she
received the same message over MEG’s texting environment. She’s trying to
get out of Coloane, but if she can’t, she’ll head to a hill just north of the golf
course that’s 300 feet above sea level.
A text message tells you to head to the hills west of Macau if you can get
there. You have no car, but one of your coworkers does, and MEG’s map
shows that he’s driving toward the Zhuhai Avenue Bridge on Macau’s west
side, which he discovered was open by reading a post on MEG. You text him
to pick up you and two other people neither of you know personally but
whom you engaged via MEG, and you all agree to rendezvous nearby. You
meet there and squeeze into your coworker’s car and drive over the Zhuhai
Avenue Bridge and veer south to the Nanyuan hotel. They all clamber out
and hike up into the hills above. You stay behind in the rapidly filling hotel
parking lot while you follow your wife’s progress on MEG’s map as she and
her friend try to flee Coloane. Using MEG, they found a friend who has a car.
The map shows that all the bridges north of Coloane are down, and traffic is
backed up behind them, so they drive instead toward the Estrada Flor de
Lotus Bridge to the west, which the map shows is still open. They then drive
west, north, and finally east to the Nanyuan Hotel. You run to her at the back
of the parking lot, and as you embrace she apologizes for being late as usual.
Then you both hike up the hill.
At 10:33 A.M., the tsunami hits. From your perch in the hills west of Macau you
watch, terrified, as the tsunami tears through large swathes of the city and
surrounding countryside. But you’re safe; the tsunami’s waters don’t even
reach the hotel’s parking lot below you. You wonder who among your
coworkers survived. After examining Macau’s online maps on the MEG site,
you see that all of them are in the hills around you, among the thousands of
people who’ve made it to safety here.
By 1:00 P.M., the tsunami has receded. MEG’s text messages suggest that aid
groups are already responding, and the US Navy is on the way with
emergency supplies and help. You and your wife read posts on MEG hour-by-hour as the horror of the earthquake and tsunami hit home: more than
100,000 people killed and more than $10 billion in damage. Truck convoys
bring in food, sleeping blankets, and tents, and helicopters bring in medical
supplies for the thousands of people stranded in the hills above Macau. You
read about five separate people trapped by earthquake debris who were
found by sending text messages to MEG; rescuers geolocated two trapped
victims from her text messages. You also read about dozens of people
stranded by the tsunami who found rescuers through MEG.
The MEG solution saved countless lives today. It was the only functioning realtime
information source during the disaster. The thousands of tweets, photos,
videos, and personal stories by tsunami survivors that are archived on the
MEG make for riveting reading. A month later, its members visit it mostly to
reflect on how they survived the disaster. New feeds appear in it to explain
how to file insurance claims and how to rebuild damaged buildings and
homes. With the help of those posts and your insurance company, you file a
claim for your and your wife’s personal items, which you left back at your
hotel before the tsunami.
Two months after the earthquake, a Macau newspaper claims that far fewer
people would have been killed if earthquake experts had given advance
warning of the tsunami. The newspaper hints that this lack of warning was
purposeful: Western scientists in league with their governments, it claims,
wanted to destroy Macau. Many people in Macau believe the newspaper.
You email the newspaper to point out that earthquake experts all over the
world warned of a tsunami more than an hour before it hit, but Macau’s
infrastructure simply wouldn’t let enough people leave the city in time. The
reporter who wrote the story emails you to say, “You’re wrong. Prove it.” You
send her and her editor an invitation to join MEG, with its visualization tools
for the archived trove of the earthquake and tsunami information, and you
send the same invitation to two other major newspapers in Macau. Then you
ask selected friends on MEG to send the same invitation to the editors of the
top 25 newspapers in the world. The newspaper that published the original
story prints a retraction, and the reporter who wrote the story resigns. These
events and the resulting news bring a burst of new members to MEG, all
seeking to find out what actually happened during the earthquake and
tsunami. A reporter at The New York Times uses the group’s trove of
information to write a long analysis of what happened during the Macau
disaster. It’s reprinted in newspapers around the world, and MEG suddenly
gains millions of members.

The technologies for this scenario and others far less dramatic already exist.
Social media applications have progressed beyond mere “social” software to
become major players in historic events such as the Arab Spring uprisings. This
paper lays out a vision of a new kind of social platform that in addition to
mining traditional interest-based communities also mines online sources to
look for significant events. The platform would invite people to form dynamic
online communities that focus on significant events. This system would
efficiently monitor, memorialize, mine, and monetize temporal occurrences of
any kind, such as sporting events, concerts, political rallies, sales, corporate
mergers and acquisitions, centennials, celebrity deaths and births, and more.
We call these ad hoc, event-driven communities Social Edens. To retain the
interest of a Social Eden’s members, the platform would continuously monitor
interactions in the Social Eden and provide members with stimulating,
relevant content and tools that match their interests. In addition, a software
player could develop the infrastructure to support community-building
features that let users or corporations personalize these Social Edens. The
software player would gain huge benefits and cachet as the first mover in this
space. The player could, for example, commercialize Social Edens with
community-targeted services, or mine their content for other collaboration
services that no one yet envisions. A player with solutions in news media,
social media, and devices could build such a service relatively quickly. Being
first to market and achieving deep penetration early would be the keys to
success in this endeavor.

Seems particularly poignant in the context of recent events, doesn’t it? And of course you can see how Mr. Gates might’ve just turned the page. While everybody else was locked into the template, we decided to take a brave new tact, and it worked. So break the mold, throw out the template, and start telling stories. Start getting the idea across in consumable ways that matter.

In the next installment, I’ll tell you how we broke this story down into a traditional requirements document.

Posted in: Agile, Technique, Writing