Can technical writing suck less

Question

I currently have the prospect of writing a considerable amount of technical documentation (describing interactions with an extremely complex online service). I consider myself a reasonably proficient creative writer but that never seems to do me any good when writing tech docs.

The problem, of course, is the dryness. You can't explore the feelings and emotions of the Chromecast when it betrays the TV. It has to be 1. plug in 2. connect 3. watch.

There is the very (extremely) informal approach to documentation that a lot of consumer goods acquire but I often find those a little cringeworthy.

So is there a way to write technical documentation that doesn't put you to sleep, but also treat the reader like a three year old.

Is there a way to write 1. plug in 2. connect 3. watch. that the reader can feel engaged by. Is it possible to marry technical writing and creative writing successfully.

I would be very curious to see any examples that you think might have solved this problem.

Answer 1

The number one thing that you have to realize about technical writing is that people do not read it for its own sake. They read it because they are trying to do something and they need more information. The writing does not need to engage or entertain because the reader is already engaged with the task. It is their engagement with the task and their need for information that drives them to read on, not their engagement with the text.

And for this reason, technical writing should not attempt to engage or to entertain. Anything you do in that area just gets in the way of what the reader wants: getting the information they need to get back to the job they were doing.

Plainness and clarity of instruction and description are therefore key virtues in technical communication. That should not make technical writing a dull job, though. Rather, it presents a different set of writing challenges.

Making ideas, concepts, and tasks plain and clear is a challenge in its own right. And because the reader is often coming to the documentation with false ideas about how things ought to work, there is a real challenge in how to engage them and their thought processes and how to put their feet on the right path, particularly because their attitude is "just tell me which button to push!"

Finally, remember that while in all other forms of writing your goal is to attract and keep the reader's attention, in technical writing the goal is to get them back to what they were doing as quickly as possible. The less time they spend reading and the more time they spend successfully doing, the better your technical writing is.

Answer 2

This question touches on one of the central ideas of technical writing: topic-based authoring.

Your paradigm example, "1. plug in 2. connect 3. watch." is a specimen of the "task" topic, but there are also (at least) 2 other types, namely "concept" and "reference".

Adding a short concept topic describing the benefits of performing steps 1-3 would be more engaging, and absolutely fall into the remit of technical writing.

Techincal writing aims to take the perspective of the "user", whatever it is they're "using". So it has the potential to be very imaginative and creative.

One example that sprung to mind is the instructions or "rules" for games. Some of these books can be so engaging that a lot of fans just read the rulebooks without actually playing the games (I know I have, and I notice people on discussion forums for e.g. roleplaying games reporting the same fascination).

I agree fundamentally with @mbakeranalecta but I would gently contest the idea that the reader is always engaged with the task you are currently explaining - part of the job of writing help or FAQ is to help the reader figure out what problem (s)he is actually trying to solve; the more complex the subject, the harder to identify your knowledge gap, and the more imagination it's going to take to get the reader from "there" to "here".

Answer 3

I think what you are missing is that all writing tells a story. Just because there is no love story or car chase, that does not mean your technical writing is not telling a story. You are just telling the story of hooking up a Chromecast. That is actually an exciting story for people who just got a Chromecast. They are your characters! Don’t diminish their excitement with crappy writing. Get excited along with them — we’re Chromecasting! — just as you would get excited along with a fictional character who is falling in love or having any adventure.

Get your head right, get into the story, and then write a personable, concise, helpful, plain language, understandable-by-all guide to Chromecasting that is a joy to read and use and that improves people’s lives by making their new Chromecast setup into a fun event with maybe a minor pitfall here and there that was easily solved, rather than a horrible chore that robbed them of hours of their precious life and then left them disappointed.

Instead of a fictional character waiting for you to tell them what to do, you have a community of real characters waiting for you to tell them what to do. You can make a million lives better with great writing. It is a serious responsibility and a great opportunity to grow as a writer and as a person.

Answer 4

I agree with @mbakeranalecta that the purpose of tecnical writing is not to entertain but to inform.

I recall a textboook on software development that I had in college where the text was regularly interrupted with little stories about "Sally's first day as a programmer" and the like. These stories were presumably intended to liven up the text while illustrating poings from the chapter. Personally, they just made me feel embarassed for the author. The stories were not only mostly irrelevant, but lame and cloying. "Oh, how exciting it is to work in the real world of software development! Sally exclaimed." It was just dumb.

That said, I think it can be good to break the tedium of dry material now and then. I wrote a database book where I got a cartoonist to draw some cartoons for me that I THINK were not-stupid, maybe one for every chapter or two. I wrote a user's guide once where in the section describing how to add and delete users from the system, I introduced the section on how to restore a deleted user by saying, "If you delete a user, and then they come crawling begging for their old job back, you can restore the user by ..." Okay, not the sort of joke that will have people roaring with laughter, but I figured it was worth a chuckle and helped lighten the mood. I think that sort of thing is helpful.

But I would be very careful not to overdo this sort of thing. One little joke every ten pages can lighten the mood. Even if the jokes aren't very good, the reader probably won't mind. It's a break. But if you do it constantly, readers are eventually going to be saying, "Hey, I'm trying to learn how to operate a Foobar, not hear a bunch of your lame jokes."

Answer 5

If you have a background in programming, take a look at Kernighan and Ritchie.

I swear that half of the reason Unix became so popular was the truly amazing quality of that book and a few others like it! I know it definitely inspired me!

At the other extreme, try looking at Unix/Linux man pages, which, while clear, almost never explain anything or even offer usage examples.

Many programmers just don't want to take the time to explain things to lesser beings, or they find it very difficult.

Once you know enough to design and implement something, you know way more than any typical user of it ever will (or would want to!) There are so many facets and underlying background skills needed, that to be competent, many of these have to become second nature, or, to use one of the most pernicious words in the English language, "obvious". When you're close to something like this as a programmer (or to any other intense area of subject expertise), when you simplify it down to what you think are the basics, it may still be incomprehensible or at least confusing to a user.

Also, you probably wouldn't be working on it if you didn't already understand what problems it will solve and why you would want to use it. Things like this are assumed by the programmer before they even start developing and become somewhat unconscious or "obvious".

It can be a major task to discern what most of your audience would be likely to know and understand and then to provide those things which are necessary to bridge the void between them and the technical information you are presenting.

If you present too little, then some readers will be lost or misdirected (see lots of SE questions where people ask about those cute little strings of gibberish which are really fork bombs - some of which have already crashed the OP's computer.)

If you present too much, then people stop reading, feel insulted, get lost in irrelevant details, or mutter things at you about TL;DR !

It is a very special (if usually unsung and under valued) achievement to write something in such a way so that someone who reads it comes away from it saying something like "I didn't know it could do that!", "I can't wait to try it myself!, or "Now, I see!"

You may not have dragons to slay, but if you can make someone feel confident enough to even approach a monster like gimp or inkscape (Those are the sorts of things I usually keep in closets that I'm afraid to open!), then that's a big deal.

There's a huge space for technical writers who can actually explain and teach things - not just document them!

Answer 6

I would say first to take your ego out of the equation. Technical documentation serves a specific purpose, which is to impart information from an authoritative source to a reader. Superfluous information, such as humor, is a distraction.

Say I want to connect my DVD player to my new flat-screen TV. I don't want to hear about how your grandfather poo-pooed color when RCA introduced it. How does that help me complete the task? Here are the criteria for technical docs, in order of importance:

Is it accurate? Is it complete? Is it appropriate?

Stick to the task and the facts. If you are new to the game, find a good editor, hopefully one who is conversant in the field, and pay attention to their comments.

Answer 7

I would basically agree with the accepted answer that the main goal of technical writing is to assist someone in a task and it should focus on that. (Most of the time) you want to get a specific job done and fast. I would say most of that applies to online documentation that needs to be terse like short howtos or reference.

However I do disagree that this must apply to all technical documentation and that you must always restrict yourself to dryness. I see no harm in being informed and entertained (if possible).

I think there are several ways to put some fun into documentation.

• Use a good design that makes the docs easily readable and aesthetically pleasing
• Add images (and or videos) to visualize things
• The problem with humor is that not everyone appreciates it. But, if you know your audience well, I think there is no harm in a pun or comic once in a while if it fits, example: https://pbs.twimg.com/media/DldA_cIXgAADj5w.jpg
• Another example for terseness and fun to look are some technical sketchnotes. The technique can come in handy for cheat sheets
• Add analogies and images to explain things, Example: "An introduction to HTTP/2 for SEOs" by Anthony Krierion which uses an analogy of a truck for a HTTP request.

---

• Source: https://www.explainxkcd.com/wiki/index.php/File:analogies.png
• License: https://xkcd.com/license.html

Answer 8

One way I use is to make a little joke in between. Like 1. Plug in. 2. Do it again, this time upside down, you got it. 3. Connect. 4. Watch.

Burgess used something like this in Earthly Powers. The protagonist had grabbed an artificial leg and Burgess was describing how he was handling it as a weapon (the technical point) and then he said that it was like he was an artificial leg seller and thinks something like 'Here lady look at the quality of this leg, the best leg you'll find' and then he swings it at some person. (This is not the exact quote.)

Or you can write some description in between, like

X was reading the manual '1. Plug in', it said. X plugged it in. 'Nice. Next step now: 2. Connect'. 'All right! Let's connect...'

etc.

This is something you can do quite easily and keep the interest of the reader.

Answer 9

Clarity in your technical writing should always be the top priority, but that doesn't mean you have to sacrifice an emotional connection to the reader.

I think I would take an approach that's similar to the way some websites do copy writing. As a copy writer, you wouldn't imagine you were telling the tale of Chromecast betraying the TV. Instead, you would imagine you're writing the dialog for a single roll in a drama that's playing out in your reader's life. Your reader is the main character in this story. You, or rather your manual, is the helpful friend. The big, frustrating, technical thing they're trying to set up is the antagonist.

When writing like this, keep in mind the story already started without you, before the reader picked up the user manual. Once they start reading it's your job to expect the emotional state they're in and try to amplify it if positive, or diffuse it if negative.

Try to think about the situation your reader is in. Are they frustrated that they can't get something to work? Or are they super stoked that they just got a new toy to play with? Adjust your voice and tone to suite the likely situation. You may even need to adjust your tone throughout the manual. For example, the introduction might be chipper and enthusiastic, but a troubleshooting section might shift into a more sympathetic tone.

You don't need to crack jokes, or add in fluffy extras that don't move the reader toward their goal. But you do need to understand who your reader is, what they're doing, and why they're doing it. With that, you can guess the kind of person they would want help from in their current situation - dad? a trusted doctor? their buddy from work who just set up his system yesterday? Once you figure out who that is, use that person's voice. Think about the level of formality in the words you're choosing and the complexity of your sentence structure.

If I want my dad to explain something to me, maybe I want extra details so I can learn how to do the thing on my own. If I want a doctor to explain something to me, I expect more technical language (in fact if it was too simplistic I might not trust the doctor!) If I want work-friend to explain something, I might expect simple steps to just get it done - full sentences but no extra tidbits about why it works.

MailChimp (an online newsletter delivery service) excels at using a consistent, friendly voice across their website, even when talking about technical things. They adjust the tone to fit the circumstance so readers never get a corny joke cracked in an error message. While they might crack superfluous jokes, they never get in the way of understanding.

The MailChimp Voice and Tone Guide is an excellent place to start to wrap your head around writing like this.

Answer 10

Lots of great answers here. One of the best examples of creative user manuals I've come across recently is this: http://jamhub.com/docs/JamHubOwnersManual_English.pdf

They've done a great job writing for highly technical users who love the techy detail and don't want to be talked down to, and 'plug play' style users who just want to get going with the product but would be confused by the techy stuff.

Shows what's possible when you think of your audience!

Hope that helps.

Answer 11

How do you spice up content creation when you are writing technical instructions? Well, you obviously can't use too many epithets or metaphors. There's little place for emotions in technical documents. However, some companies are trying to use technical writing as a tool for establishing or further promoting their company's image.

A good sense of humor, for example, can be a trait your company is known for. And, this means, that even your help topics might have a couple of jokes in them. Google, for example, does that in online documentation. However, Google's got a whole team of experts that are trying to figure out what is appropriate. Moreover, these experts are studying other cultures as well, to make sure that localisations meet ethical and cultural specifics of different countries.

Not every company has the resources Google has, so, in order to avoid leaving a negative impression, mostly people choose to stick to the safer side of things in their user manuals.

I recommend that you read this article - 'How to Up the Drama in Your Technical Documentation' to learn more on this topic.