Level Up!
Published in

Level Up!

Metaphor in Technical Writing

by ClickHelp — professional help authoring tool

This is how technical documentation works — a technical writer gets a new task, does research and consults subject-matter experts to get max knowledge. Along the way the tech writer is drawing up a plan, a scheme to pass the knowledge to the readers. This is never as simple as retelling, it takes a lot of thought and effort to write comprehensive technical texts.

Skilled techcomm specialists have a hunch when it comes to choosing techniques to use for content building — they see a text, read it through and start re-modeling it in their mind right away.

There are many things you can do with a text to make it perfect for your readers. Things like lists, tables, schemes, screenshots, gifs, videos, even paragraph division work like a charm when done right.

Today, however, we would like to talk about something less technical — a metaphor. Is there a place for metaphors in technical writing? Yes, and if you are still ignoring them, we would like to change your mind.

All the World’s a Stage

What is a metaphor? Let’s look it up. Wiki puts it like this:

A metaphor is a figure of speech that, for rhetorical effect, directly refers to one thing by mentioning another.

It is also mentioned there that a metaphor may provide (obscure) clarity. Now, how is this supposed to work? As a literary device, metaphors definitely embellish a text. Also, certain metaphors can make things less clear especially on the first read — they can be complex and misleading for an unprepared audience. They can be also called poetic metaphors. These are not the metaphors we are going to talk about in this blog post. You can find them in literature and poetry. Here’s a famous quote by Orwell: “Advertising is the rattling of a stick inside a swill bucket”. That certainly makes a mind wander.

Technical writers are only interested in the ones that provide clarity, they are often called scientific analogies. Metaphors are making things clearer by giving readers a vivid picture of a thing or a process that facilitates user comprehension. And this can work even better than simply describing stuff in strictly technical terms.

Here’s an example: “…cell membranes as mosaic structure of oriented globular proteins and lipids.” After reading this, we can see a simple picture of a complex phenomenon.

Or, software development is often described as “building a house”. We all understand that there can be no house without a plan. This plan is an equivalent of developing software architecture which is crucial.

But this is not the only purpose of using metaphors. Literary devices are the means to humanize technical documents, and metaphors are no exception.

You see, reading technical documentation is not a fun ride for the majority of people. It can seem overwhelming or simply boring due to its technical nature. Looking for ways to make it sound more human and maintain (or even improve) its clarity is what has brought us to metaphors.

Another advantage of using metaphors is to make the process of creating content more compelling for technical writers as they may feel very restricted by all the standards.

Metaphors are not the only literary devices that can prove extremely useful for successful technical communication. If you are interested in this topic and want to humanize your technical documentation, refer to this blog post.


Surely, technical texts will never become literature. It defeats the purpose. At the same time, humanization of technical documents can do a lot of good to the whole techcomm society.

Technical writers have a wide range of tools at hand to improve user manuals, and overlooking things like metaphors would be a mistake.

Good luck with your technical writing!
ClickHelp Team
Author, host and deliver documentation across platforms and devices

Originally published at https://clickhelp.com.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store


ClickHelp - online documentation tool for technical writers and teams. Check it out: https://clickhelp.com/