Using literary techniques for technical documentation

“Technical writing is a continuous process of learning, carefully gathering, sifting, organizing, and assessing, all while trying to craft something that makes sense for a user.”

Krista Van Laan, The Insider’s Guide to Technical Writing

A few months ago, one of my favourite game developers released Lost Judgment. It’s a sequel to Judgment, and a spin-off of another series, which coincidentally contains a song titled Judgement. I have this song on repeat most days, but can’t even begin to express how much I dislike the word judg(e)ment. The game’s release sparked a conversation at home when my husband asked for the correct spelling.

I answered emphatically, “They’re both correct. Generally, when you add a suffix to a word that ends in a silent e, the e is dropped before a vowel, but stays before a consonant. Like blame to blaming. You can keep the e before a vowel if you want to emphasise…“

He regretted asking. It’s probably a good thing I don’t go to parties. I wouldn’t be much fun.

But it got my inner nerd thinking.

I’ve always loved English. Back in the dark ages when I was in primary and secondary school, my classmates and teachers were convinced I’d grow up to be the next Stephen King or John Grisham. I’ve at least got author in my job title, so close enough I suppose?

Do Literary techniques have a role to play?

When I first started in technical writing four years ago I envisioned myself writing long lines of beautiful prose, but technical writing is often literal and direct, and offers little room for the idioms and hyperbole we use every day. However, the discipline itself is highly creative; as authors, we take complex products or principles and convey this information as clearly as possible with the end-user and their needs in mind.

“Remember, your output is not a work of art; it’s a work product designed to help the customer – whoever the customer is.”

Krista Van Laan, The Insider’s Guide to Technical Writing

It can be hard to strike a balance. Many technical documents are filled with affectation, language that is more technical, formal, or showy than necessary. Knowing your audience helps. Take a moment to identify your readers, and consider their level of knowledge. A highly technical and industry jargon-filled document aimed at engineers won’t hinder an expert in the field, but what about documentation for the average reader?

While affectation gives a (false) sense of authority, it also alienates your reader by forcing them to work harder to understand your document. Good technical documentation should make difficult tasks easy and complex information clear.

“Good writing is often about letting go of fear and affectation. Affectation itself, beginning with the need to define some sort of writing as ‘good’ and other sorts as ‘bad’, is fearful behaviour. Good writing is also about making good choices when it comes to picking the tools you plan to work with.”

Stephen King, On Writing

So, what role can literary techniques play in technical documentation? Let’s explore some of these techniques, and how they can help (and sometimes hinder) your technical writing.

Figure of speech

“Figures of speech can help translate the abstract into the concrete.”

Gerald J. Alred, Handbook of Technical Writing

A figure of speech is a word or phrase that deviates from literal language to convey a comparison, clarify a point, or simply add some colour to your writing. Figures of speech form a bridge of understanding between a specialist and non-specialist by providing emphasis and clarity, but, when used poorly, can introduce ambiguity due to the possibility of literal and figurative interpretation. The less technical your writing is, the more you can get away with using figures of speech.

Using comparison in your writing allows your reader to link an unfamiliar idea to their own experiences and promotes investment in your writing. When used carefully and skilfully, figures of speech can humanise complex technical documentation and help make an unfamiliar concept familiar.

However, figures of speech can be a nightmare for translation and localization. A metaphor or idiom in one country can lose all meaning in another, even between specific regions the meaning can change.

Here are some examples of figures of speech and how they differ around the world:

• English: The grass is always greener on the other side.
  • Brazilian Portuguese: A galinha do vizinho sempre é mais gorda (The neighbour’s chicken is always fatter).
• English: Piece of cake.
  • Japanese: 朝飯前 (Before breakfast/Can be done before having breakfast).

Metaphor

A metaphor is a figure of speech that directly refers to one thing by mentioning another to help explain an idea or make a comparison. Metaphors add flourish to your language by equating two things, not because they’re the same, but for the purpose of symbolism or distinguishing a comparison.

Lakoff and Johnson’s Metaphors We Live By theorises that human cognition is metaphor, and as such, metaphors are a fundamental mechanism permitting us to use our physical and social experiences to better understand numerous other subjects.

Although metaphors are seen in literary writing as an effective means of communication, they are generally avoided in technical writing where clarity is key. Enter scientific analogies.

Scientific analogies, a form of metaphor used to make complex processes or ideas easier to understand, are prevalent in the language of science. Analogies are frequently used to interpret results and communicate observations. Consequently, this use of metaphors grants non-experts the ability to understand abstract ideas and gain new insights and knowledge on products and processes.

In technical writing, scientific analogies allow you to make the unfamiliar familiar by deliberately simplifying your writing to relate to general audiences who may lack sufficient understanding and background knowledge on the subject.

“Analogies, it is true, decide nothing, but they can make one feel more at home”

Sigmund Freud, The Essentials of Psycho-Analysis

Simile

Similes are so common in everyday speech and writing that you likely don’t notice them, but you definitely understand their meaning. A simile is a form of metaphor that compares two unrelated things for the purpose of hyperbole, irony or comparison and connects them with prepositions. If you see a comparison connected with like or as, chances are it’s a simile.

All similes are metaphors, but not all metaphors are similes.

Similes, like metaphors, can be used as a method for engaging your audience, but using a simile appropriately for a technical purpose takes skill, and it is recommended, in situations in which literal language is mandatory, to keep your writing simile-free.

Parallelism

Parallelism is a figure of speech where two or more elements have the same or a similar grammatical structure. Parallelism is used for effect and intends to draw comparisons, emphasise, elaborate or link an idea.

In the literary world, parallelism is an effective means of capturing a reader’s attention and enhancing writing structure, which can make text more meaningful. However, use parallelism too frequently and the effect is lost. You wouldn’t expect to find parallelism in technical writing, but it’s there.

Parallelism exists in technical writing in the form of consistency. For example, a user manual advises to “1. Navigate to the main menu. 2. Select the New button. 3. Touch the Create icon.”. Using parallelism, we can tidy up the steps, “1. Navigate to the main menu. 2. Select the New button. 3. Select the Create button.”. It’s a subtle change that brings an element of consistency to your writing.

Conclusion

The use of figures of speech is significant and abundant in writing and when used responsibly, metaphors and other creative literary devices can enhance technical communication and increase effectiveness by facilitating understanding and bridging the gap between the technical writer and their audience.

Technical writing is a balance between subjectivity and objectivity, and creativity with clarity. When deciding whether to use figures of speech in your documentation, consider if the document is one that calls for, or would benefit from, a less formal tone and more vibrant imagery. Get to know your target audience and their knowledge levels, put yourself in their shoes and ask yourself if such comparisons will benefit their understanding or potentially hinder it.

If the answer is the latter, leave your literary devices to the John Grisham’s and Stephen King’s of the world.