10 Commandments of Storytelling as applied to Tech Doc?

One of the topics I am slated to deliver at various conferences in 2009 is my presentation on why I think “Technical Writers Shouldn’t Be Writers.”

Towards the end of that presentation I have a slide that mentions four recommended books as “must reads.” One of those four is Robert McKee’s “STORY: Substance, Structure, Style and the Principles of Screenwriting.”



Anyone who reads this blog will know that I’m a strong advocate of storytelling in all forms of communications. I believe that it applies as much to technical or marketing communication as it does to your favorite novel or movie.

It seems I’m not alone in that thinking. Over at the excellent slide:ology blog a recent post applies McKee’s “10 Commandments of Storytelling” to PowerPoint Presentations.

Picking up on that thought I decided to see if I could apply McKee’s 10 Commandments to Technical Documentation.

1. Thou shalt not take the crisis or climax out of the protagonists hands.
So who is the “protagonist” of your documentation? It could be your product, but the most likely candidate is that your “protagonist” is the person using your documentation. Your documentation should be written in such a way that your protagonist can use the information so that they feel that they have solved the crisis (or put more prosaically, overcome the problem they have) themselves based on the knowledge you have presented. Another story telling trick, often cited by screen-writer Todd Alcot, that is worth remembering – ask yourself “What does the protagonist want?”

2. Thou shalt not make life easy for the protagonist.
This seems contrary to the very purpose of Technical Documentation. Isn’t it our job to make life easier? Yes it is. But in certain types of documentation, such as training materials, you may want to include challenges, and then guide the reader through them. This way you can build a sense of accomplishment as the reader progresses through the material.

3. Thou shalt not use false mystery or surprise.
Don’t hold back anything that is integral to full understanding of the product or service you are writing about. But also make sure to reveal information in a logical manner that is considerate of the reader’s needs. Make sure they have the information they need to know, at the time they need it.

4. Thou shalt respect thine audience.
The first rule of any sort of writing is “know your audience.” Know them, and respect their level of knowledge. If you are writing something for experts, then you may not need to include the basic information that you might use for a more general consumer market. The use of conditional text is a great way to handle different topics and statements designed for different audiences within a common documentation set.

5. Thou shalt have a god-like knowledge of your universe.
A joke I often use is “What’s the definition of an ‘expert’?” – The answer is “it’s a person who has read two more pages in the manual than you have.” So what does that make the person who wrote the manual in the first place? We may not know everything about what we are documenting, but we should give the reader the confidence that we do.

6. Thou shall use complexity rather than complication.
Most of what we write about in Tech Doc, is by its very nature, complex. We should take that complexity and break it down into logical steps and topics that can guide the reader. We should never use complexity as an excuse for making the documentation complicated.

7. Thou shalt take your character to the end of the line.
We learn in grade school that every story should have a beginning, a middle, and an end. The same applies to documentation too. The narrative should guide the reader through the process, or information, in such a way that it flows logically, and that at the end they know more, or have achieved more, than when they started.

8. Thou shalt not write on the nose dialog.
Wait, I hear you asking, there’s no dialog in Tech Doc – so how does this apply? Well the definition of “on the nose dialog” relates to the scene when a character says aloud, exactly what he is thinking or describes what is happening around him. So how does this apply to Tech Doc? Do you have sections of doc that are restating the obvious? Try reading your docs out aloud? Is it boring and repetitious? Try altering sentence lengths. Don’t think anyone ever listens to docs as if it was dialog? As a teenager I spent hours working under cars while a buddy nearby would read the steps from the manual for me to follow. How about a visually impaired customer using a reading device?

9. Thou shalt dramatize thine exposition.
Put simply “show don’t tell.” In prose this means have your characters reacting to an event, not talking about it. But isn’t our job to tell people how to do something? Yes it is, but the key word is “how.” Replace long descriptive texts on operational theory with a few active steps the user can take themselves, that demonstrates the product, and they will gain a quicker understanding. People learn more by doing than they do by being told.

10. Thou shalt rewrite.
Do I need to explain this one? Plan your schedule with time to write, have someone else review, and rewrite. Best of all scenarios is to write, have someone actually use your draft to accomplish the tasks you have written about, get feedback. Better yet, watch them try to use your docs. Then go back and rewrite based on your observations. They say that any good piece of art is never finished. Writing is art, even Tech Writing. You can always improve on what you’ve done.

Banging The Drum Again...

In his excellent blog post about the current state of the book publishing industry Mark Tavani, a Senior Editor at Random House, makes the following observation.

... books are a mere format. Yes, they can be beautiful and wonderful to hold in your hands, and yes, there are some books I plan to keep in my home until the day I die simply for their sentimental value. So I understand what is magical about books. But the most magical thing about them is the information they convey: the story they contain. The word “book” and the word “story” are not synonymous, just as eight tracks and music are not the same thing. Stories pre-date books by milleniums; and though books might someday go away, story will last as long as our civilization does.

Substitute the word "book" for "documentation," and the word "story" for "content" and I think the observation applies equally to the world of corporate publishing as it does to traditional book publishing.

=========

I need to add a couple of points of clarification here.
- Anyone who knows me and has heard me speak will know I love books (the traditional kind). I have a house full of them, and spend my evenings and weekends writing them. BUT while I'm a passionate bibliophile, I am also aware (as I mentioned in my last post) that the "book model" is perhaps no longer the best model to be using to ensure that content reaches the end user of a product or service.
- While I suggested swapping the word "story" for "content" in the quote above, that was more to illustrate a point. For me everything we write or produce that is designed to pass on knowledge or information is, and should be treated as, a story. The ability to tell stories is the most powerful communications tool we have at our disposal. As Tavani points out, we've being doing it for millennium, and will continue to do it irrespective of any technology or medium.

Move over DITA – Chaos is coming!

I’ve never really questioned the need for hierarchical structure and imposed taxonomies, - until I watched my teenage daughter doing her homework several months ago.

Let me explain.

I’ve been working with topic based authoring, structured content and mark-up languages for over twenty years now. This highly formalized approach to technical documentation has always seemed to be the right approach to take in handling larges amounts of complex information, and delivering it in a way that enables relatively easy navigation.

I’ve seen them all come and go – SGML, DocBook, XML, CALS, DITA plus a ton of various industry and company standards. I’ve even served on several such standards committees and working groups in my time.



For those of us raised on more traditional media (i.e. the printed word) we are most comfortable with the book paradigm. That information should come in a structured format, i.e. Chapters with Headings and Sub-Headings, and that navigation is best accomplished by either a map to that structure (i.e. a Table of Contents), or an alphabetical listing of subjects covered (an Index).

Naturally when we started to deliver information electronically we carried that paradigm over. Sure we made a few concessions to the new media (for instance I remember having a long, and somewhat heated discussion on why we didn’t need page numbers on a CD deliverable); but the underlying print based model stayed. Because that’s what we were comfortable with. It’s what we naturally understood and it matched the way that we handled locating and using written information outside of the work environment.

In fact for most of my working life to date, the technology I used at work far out paced that I used outside of work.

But not any more.

Now the technology I use at home has generally outpaced that found in most workplaces. In particular social media and the way that we look for information online.

Helping my teenage daughter with a school project on Pearl Harbor made me realize that the new generation now entering the workforce has a completely different way of accessing information.

Of course the first thing she did was google “Pearl Harbor” and started visiting links. First stop was Wikipedia.



Then she got on Facebook and YahooIM and started using messaging to ask friends who were online for recommendations. These friends were literally from all around the world, so she was given access to resources that gave totally different perspectives than those given in the classroom. As I watched she soon had six different windows open on her iMac and was pulling information from multiple sources into her own document. Building the structure and narrative as she went.

One friend suggested going to a social bookmarking site and searching using a variety of user applied tags. Instead of taxonomy she was now applying folksonomy.

Of course being a bibliophile and a bit of a history geek I had a few good old-fashioned print books on World War II sitting in my home office. I proudly placed them on the edge of my daughter’s desk and suggested she look through those for information on Pearl Harbor too.

She dutifully picked up a couple of the books and started flicking pages over, skimming through the contents.

“Why don’t you use the Table of Contents of Index?” I asked.

“That just confuses me. I can find stuff quicker this way,” she replied, looking in bemusement at her obviously aged father.

I sat back and watched her navigate the books for a few minutes. She quickly found what she needed – and then I realized what she was doing. She was “browsing” just as if she was online.

That’s when I started to question the paradigm that’s informed the way I’ve thought about online documentation for over two decades. The book driven, structured paradigm may have been ideal for my generation, but what about the new generation?

For kids raised as part of the “digital generation” where the first place they go to find out information is the internet and social networks, is the book an irrelevant model?

Yes the information they access still needs some sort of mark-up and tagging so the search engines can find it. It still needs metadata to enable user tagging. But instead of strictly enforced hierarchies, what is being built and accessed is more of a flat ocean of information (or a “Content Pool”) that users search rather than navigate, and then dip into to find the components they need to build their own solutions.

So where does that leave current favored structured standards like DITA? I believe they have a place in more rigidly defined and regulated environments, but how long they will remain useful is open to question.

As for more general applications I believe we need to stop trying to shoe-horn the current “flavor-du-jour” standard onto every publishing project, and instead take a step back and look at how your kids do their homework. Because in five to ten years they will be your new workforce, and perhaps more importantly, your new customers.

Remember the (STC) Alamo

Just over a week ago I attended what was simply the most open and stimulating regional STC event I have ever been to.

The Central Texas STC Fall Seminar, was organized jointly between the Austin and San Antonio chapters of the industry group and held at the excellent Hotel Valencia on San Antonio’s famed Riverwalk. (Home to many fine restaurants - including the one where we had lunch.)



But it wasn’t the setting that made it memorable – it was the participation.

In my experience a lot of these regional get-togethers end up in features and functions comparisons of tools, minutiae of the job, or arcane technical discussions about standards that only a minority of people use. Not so in this case.

The discussions ranged from using emerging new technologies, Web2.0 tools,, wikis, social networks, to how to develop and recognize metrics, to how to make sure that the documentation process is heard and accounted for in a Agile Development driven world.



But underscoring all the talk of technology was the realization that technologies will come and go, and the most important skill to develop was the ability to learn about new things, and communicate that in an empathic way.

There were several people who were attending their first STC event and they, along with everyone else, left with the impression that this is an exciting time to be in the corporate publishing world.

Is there a case for "Just Enough" Documentation?

A couple of what at first glance appear to be disparate unconnected posts picked up by my Twitter feed over the last few days got me thinking about just what we should include when we produce product documentation.

On her Twitter feed consultant Sarah O’Keefe posted the following quick observation: "Inbox Zero once again. Today's lesson: When you ignore stuff, much of it becomes irrelevant.” This is a productivity, time management technique that I have used for years. One of the first things I was taught at management college was that never keep anything on the “to-do” list longer than 30 days. If you haven’t got around to it in 30 days and no-one’s complained it probably wasn’t that important. Delete it, and if it is important someone will remind you. Like Sarah I also apply a similar philosophy (but not time scale) to the contents of my Inbox.

Then today, Alyssa Fox from NetIQ posted a quick note on her Twitter feed that “SE just found a bug in our doc that's been in there 5+ years. Obviously no one ever reads that section,” to which I responded “If no-one's read that doc in 5 years - is it really necessary to have it there at all? Why write and maintain something no-one uses?”

Over lunch I began to realize that the two thoughts had a definite connection. Traditionally we tend to document every feature and function of a product. We expend many hours describing how something works. Yet how much of what we produce is ever read or used?

Most users are only interested in learning how to set something up and start using it in the shortest possible time. Secondly they want to get answers to very basic “how do I” type questions. With this in mind I’ve recently been conducting an ad-hoc, and very unscientific, straw poll about which documents (print, on-line help etc.) that people are most likely to use. The result is very clear that the thicker and more voluminous the documentation appears, the less likely people are to use it.

So going back to the “ignore it and it becomes irrelevant” thought. If sections of documentation are never read, accessed or used, are they irrelevant? While the engineers and designers may not think so, it seems clear that the users do.

Is there a case for “Just Enough” documentation.

At WebWorks.com we recently went through a process of rewriting our complete documentation set. At least that was the original goal. Yet when we compared the old documentation set against the project time frame we realized that we would have to make a decision about what was necessary and what was just “nice to have.” The project was lead by one of our MVP users who could give us the user perspective on what was needed and what could be left out.

But how will we know if we’ve made the right choices?

We posted the new documentation set online as a wiki. We have enabled comments so users can directly tell us if there’s something we missed. If we need to, we can create a new piece of documentation and publish it quickly. But perhaps best of all we can now track which document pages are visited and more importantly which aren’t.

It may take a few iterations but we will be able to fine tune the documentation to provide just the information that our users need and use; allowing us to focus effort away from maintaining “irrelevant” dead pages to making sure that he have “just enough” documentation to make our users successful.

[This entry is cross-posted to my WebWorks.com blog]

STC Proposals #3 - What Tech Doc Can Learn From The Comics

Proposal for a paper to be presented at the 2009 STC Summit in Atlanta, GA

#3 - What Tech Doc Can Learn From The Comics

The recent Google Chrome comic caused a lot of buzz. But it's far from being the first "technical" comic. Find out how comics can help you produce better tech docs.

There is a long tradition of connections between the worlds of comic books and technical documentation, but it is one that is often overlooked. (For example the US army has used technical comics for over 50 years)

This presentation will present examples of technical documentation done using comic book techniques from over the years to the present day.

It will also show how by studying the story telling and artistic techniques used in comics we can improve the readability and quality of technical documentation.

STC Proposals #2 - How To Make Executives Love The Publications Department

Proposal for a paper at the 2009 STC Summit in Atlanta, GA.

#2 - How To Make Executives Love The Publications Department

"The publications department gets no respect" is an often heard refrain. But it need not be that way.

It is possible to make Publications one of the most respected groups in your company?

Building on my own experience of doing just that, this presentation will show five key steps to take in order to change the way people think about publications.

The lessons presented can be applied equally to a single writer, as well as to larger publications groups.

STC Proposals #1 - Move Over DITA, Chaos is Coming

Last week I submitted proposals for three papers for the 2009 STC Summit in Atlanta GA, and thought it might be fun to post the summaries here. Let me know if you'd be interested in hearing any of these and if so, what sort of questions you'd like answered or topics you would like me to cover.

#1 - Move Over DITA, Chaos is Coming

The Technical Publishing industry is on the edge of a paradigm shift and may not realize it.

As the digital generation enters the workforce they will bring new expectations with them that will challenge the way we write and deliver content.

This presentation will contrast the way we currently produce documentation and our expectations of user behavior with what we can expect our users to be asking for in the not too distant future.

In the world of social networks, online video, wikis, blogs and twitter is structured topic based authoring really the answer?

Reflection on Santa Fe

I must admit after last year's excellent CIDM Best Practices conference, this year's event in Santa Fe was a little disappointing.

I didn't really hear anything new from the presentations, while the networking and side conversations seemed somewhat subdued. I had a couple of good productive pre-arranged one-on-one meetings, but otherwise there was no real discernible "buzz" about this year's event.

Difficult to say why, as that's more of a subjective feeling than an objective observation.

One thing that did surprise me was the fact of how many people still overlook both the importance of graphics, and the impact of the whole publishing process once the content has been created.

Creating good technical documentation is not just about authoring and content management.

NM bound

This weekend I'll be on the road heading to Santa Fe, NM to attend the upcoming CIDM Best Practices conference.

I'm looking forward to the conference, meeting up with some old friends, and hopefully learning a few new ideas and concepts about the art of Corporate Publishing.