: Re: Can technical writing suck less I currently have the prospect of writing a considerable amount of technical documentation (describing interactions with an extremely complex online service). I consider

@LarsenBagley300

Vote Up Vote Down

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.

(0)

Login to post a comment!