Narration in Technical Writing 2

Posted on November 19, 2013


In Narration in Technical Writing 1, I talked about using a “movie trailer” intro to “sell” a technical idea under a show-don’t-tell approach. Here I’ll talk about how to take  that that dramatic lead and convert it into requirements.

From Narrative to Requirements

“Storytelling is the most powerful way to put ideas into the world today.” —Robert McKee

When Yoav, the originator of the Social Eden idea and I originally met, we had 15 minutes for me to consume an idea he had been percolating on for 15 years. He started by saying “Both of my parents were concentration camp survivors…” Boy, what a lead! He certainly had my attention. He then went on to discuss how telling stories (history) has changed and how we can now dynamically record it and use tuples to bring it all together into a new type of social media platform built dynamically around historical events (e.g. the Hades earthquake).

Fifteen minutes isn’t long, but it was enough to get started because he basically laid it out very similarly to how we eventually published it, describing a scenario and how he envisioned the application working.  I went away and  thought about it for a while, and some of the very interesting things he said. The thing is, most people will tell you their ideas in the terms of an example or a story. We always discount the story to get to the “requirements,”  but after all of these years of dutiful decomposition I finally realized the story is the requirement, because it contains the rich context of the idea which answers so many questions that other documentation does not. For me, it was natural to take his original example, expand on it, and use that not only as our introduction, but as the guiding basis for the entire paper.

In looking back on that paper, I can see that in addition to the Movie Trailer intro, we used narrative in three other ways.

Narrative to set the context

First we chose to tell the history of media, to position our solution, its timeliness, relevance, uniqueness, and possible issues. It gave a flavor and a fabric to the work we were doing, and it was an extension of Yoav’s original pitch.

“2. Mining stories for history

Until recently, historic events rarely spawned any contemporaneous
reporting. Before the printing press, history was oral or handwritten, and it
took a long time to compile and distribute historical texts. The first publicly
circulated documents were usually authored by governments or churches,
which had decidedly one-sided points of view. The Gutenberg bible
democratized the Christian religion and helped incite the Protestant
Reformation, just like Facebook and other social media helped incite the
Arab Spring. The printing press was born in 1440, and the first newspapers
followed in 1620. Newspapers introduced the concept of reporters—people
whose entire profession was to record and report events in an unbiased way.
Photojournalism was born in 1850, allowing people to see images of actual
events. But until the advent of the telegraph in 1844, the telephone in 1876,
the radio in 1897, and the television in 1927, reports in newspapers or letters
could take days, weeks, months, or even years to reach the public. The
advent of radio and TV cemented the idea of an impersonal version of events
by a few select sources to create a single source of truth, which then became
known as history. Despite all the technological advances of the last century,
this flow of information was stable and one-way: from source to consumer.
Today, this model is being inverted. In our socially networked world, any
event of historic significance is widely reported in a variety of media such as
Twitter, Facebook, Google+, and blogs. Events of historic significance are
reported in real time by real people; a wealth of information comes from
eyewitnesses usually before professional reporters can get to the scene.”

Again, this was part of Yoav’s original pitch to me, and I loved how the history lesson put his idea into both context and counterpoint. Researching and writing this part was one of the funnest parts for me.

Stories to services and back again

After several attempts, I realized I was not going to get the kind of access to Yoav I’d had with some other authors. This put a point on the classic technical writers’ dilemma: you don’t own the content, you just get to smith it. So I had to figure out how to validate with him that I had captured his idea.  As a person with both Service Oriented Architecture and Agile experience, I wanted to talk about the software in very high level terms, decomposing it into services. All this means is I wanted to talk about some of the large pieces of functionality we would need to account for to make the software work as described in the trailer. To figure this out I did a competitive analysis, taking bits and pieces from existing software,  and basically created a catalog of what we needed. For instance we would need a way to connect you to a community, a way to determine the accuracy of the information posted, a way to score people who are credible, a way to aggregate information across multiple media sources, etc.

I don’t want to go too deeply into the Agile methodology  for which there is a full  canon of material, but for each of these services I then simply wrote a user story, well actually an epic, to cover them, essentially creating a back log of stories the application would have to encompass. Agile is one place where people have long understood the value of narrative and so it seemed a natural fit to build a paper about a piece of software by writing the requirements as stories. Yoav and then I used these “stories” to discuss the paper and anything I had missed.  As I came across them, I constantly updated the “movie trailer” to include them.

In the final paper Mark later artfully mapped these service  activities against the chronology of the original narrative and the pillars of social media.

Telling other stories

The other thing that we did was to come up with a list of other very compelling scenarios (stories) where we could apply the Social Eden platform. I thought this was some of the most interesting and compelling work in the original paper, but alas like so many great scenes in literature and film, it now lies somewhere on the cutting room floor. (Or, as I like to believe,  it could actually be that they were so compelling as to give away the actual competitive advantage of the Social Den idea and were removed when the paper was published externally 😉 )

That’s okay, I’ll be talking about scenarios in detail in upcoming installments in this series.

Posted in: Agile, Technique, Writing