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.
