Documentation as storytelling: Diction and narration – By Nicholas Graziade

Your documentation tells your readers a story about your organization’s products and purpose or your software’s features and functionality. As your clients read, they immerse themselves in the written reflection of your creative vision. But if documentation tells a story, is the documentation itself a form of storytelling?

Storytelling has several classical components: plot, setting, suspense, language, characterization, and so forth. Each component could warrant its own article, but I would like to focus on two specific elements: diction and narrative.

Diction: the subtle message within your documentation

Perhaps your organization has embraced a casual style that carries a conversational air.

Perhaps you prefer a certain level of formality that reflects the core professionalism that inspires confidence. Perhaps your writing uses contractions. It may directly address your readers in the second person (e.g. “you will scroll to the bottom of the page”), or maybe prefer an imperative style to direct your readers (“click the navigation bar and select Drafts”).

Each of the choices you make about the way you write your documentation are a part of your diction. Keep in mind that diction in a literary sense characterizes your choice of words and language. This is discrete from enunciation or articulation: the way in which you pronounce words or stress them in day-to-day speech.

Diction comes in several flavors:

• Formal: this style uses professional terminology, structured syntax, and avoids colloquial phrases and slang. This is the most common form of business writing and often includes legal content or engineering documentation designed for developers.
• Informal: on the other hand, informal diction often feels like the conversations you have every day. If you write in a casual style that mimics the way you speak to your audience, you’ve likely embraced a more informal style.
• Academic: You can find academic or educational diction in research papers and primary literature that includes assumptions about key terms or jargon from an academic discipline. It is frequently concrete and direct.
• Poetic: Poetic diction typically carries abstraction and emotion. While you’ll rarely find documentation that is actually poetry, anything that inspires different feelings and moods includes an element of poetic diction.

Ask yourself, “what does the diction in my documentation communicate?” Language always projects a certain mood. It can be direct and serious. It can be relaxed and even amusing. While your documentation typically has a primary function to instruct, the nuances of your diction can affect the underlying tone that goes beyond the meaning of your content.

Try not to forget that diction also includes avoiding clichés and archaic terms. Sure, you can achieve a level of Renaissance panache by including words such as quoth, thou, or mayhap, you may want to dodge anything that gives too much of a Shakespearean flair! Similarly, you’ll probably want to avoid unusual or uncommon words that force your readers to pause. If your documentation makes your readers reach for a dictionary, you may want to reconsider some of your choices.

As always, keep in mind that you want to match your diction to your audience. If you write for software engineers, database experts, or other development users, you are likely to choose words that meet their expectations. Likewise, writing for potential customers or clients will probably use different language oriented toward attracting new users.

What else does my diction say? 

Your documentation’s word choice has a flipside. While it tells a story about your product, it also tells a story about you or your organization. This is the reason that so many organizations use style guides to help guide their content authors toward a common voice. For example, if you work with clientele that expects a more hands on or personal approach, informal diction may be the best choice. Diction imbues the character of your organization within your documentation and your readers will take notice!

Narration: the story itself

Narration is the activity of recounting the details of a series of events to an audience. It can be as simple as one person sharing a joke with a friend or as complex as Tolstoy’s Anna Karenina. At its broadest, narration is storytelling.

Before sitting down to write this, I asked myself a simple question to prepare: what does my documentation do for my audience? 

Does it lead my readers through a logical pathway from a beginning to an end? Check

Does it relay details that orient my readers to specific details that enrich their experience? Check

Does it is highlight important ideas to create a more vivid picture of my descriptions? Check

Lo and behold, my documentation shares a lot with narration. And, if my structured logic stands, then by the powerful laws of the syllogism, my documentation is, indeed, storytelling!

However, do my readers truly benefit from deductive reasoning that my documentation is a form of storytelling? Probably not. To that end, I almost certainly want to look beyond the simple definitions to get a better picture of not just if my documentation is storytelling, but rather how I narrate that story.

Narration brings together a host of techniques that bring your audience clearly from one place to another. Below are a few things to keep in mind to help you tell the best story you can:

• Have you ever heard a story that felt a bit longwinded or fell off into several unnecessary tangents? Keep your documentation on point to help communicate the best way to get from point A to point B.
• Make sure that everything you write has a purpose. Several documents include extraneous information that is interesting, but not fundamental to the ultimate purpose. This does not mean that you should exclude helpful guideposts for your audience (such as an alternate method to accomplish a similar task), but does mean that you need to sometimes rein in your content.
• While you may be excited about your content, make sure your documentation coveys the clarity and professionalism that your audience expects. Remember what you just read about diction? If a procedure reads like an excited youngster talking about all the cool things his latest birthday present can do, you might need to tone back your content. Over the years I’ve had to edit some unusual metaphors in user documentation that would otherwise distract an audience!
• Speaking of metaphors, comparing procedures to something your audience already knows is a great introductory technique. However, it can be confusing when embedded in a step-by-step. For example, while you may want to draw a parallel between two processes, if your reader has yet to encounter the first, the second will not make much sense! As a rule of thumb, keep metaphors in your introductions or conclusions and keep your procedures as straightforward as possible.

…and they lived happily ever after!

In the world of software documentation, this often means instructional procedures that explain how to perform a function or troubleshoot a problem. Each of these procedures has a goal and steps to achieve that goal. It is akin to a story’s scenes and moral. And while navigating from a menu to a sub-menu and scheduling a batch print job might not seem like much, keep in mind that as you relate these details to your audience in your documentation, you are exposing them to the hard work and final product that you have helped bring to life.