Writing Technical Information for Tech ‘Dummies’

24 November 2011

 

   Image by julianrod

Thanks to Stephen, one of our readers, who wrote me with one of the writing struggles he has:

 

It’s difficult to write a clear and short e-mail to my boss, in particular about the system error because he/ she may not have any technical background.

 

I’m definitely a ‘non-techy’ reader like those that Stephen has to write emails to, so I can understand his concern. Normally, if I have technical problems with my computer, I go straight to an expert for help. And if I’m forced to read any kind of technical manual or even the ‘Help’ function of Microsoft Word, it drives me completely crazy!

 

And why does it drive me crazy?

 

Because the people who write instructions for all the technical gadgets and tools we use every day simply know too much. These technical wizards know every detail about systems and hardware and software and code etc. They could take care of technical problems in their sleep. But if they have to stop long enough to explain what they’re doing, it’s very difficult for them.

 

Why it’s hard to explain stuff you know

This point was brought home to me recently when another reader wrote me about his struggle with slow typing. Turns out that he had never learned ‘touch-typing’, and so he uses the ‘hunt and peck’ method, which of course, is very slow and tiring.

 

That sent me back in time to when I first began learning to type. At first the process was slow, because I had to stop and think which letter was on which key. But by the end of the course, I was no longer thinking – just typing with speed and accuracy.

 

This is similar to the problem that Stephen and most technical writers have. If they have to ‘slow down’ to think about how to explain something to tech ‘dummies’ like me, it’s very challenging.

 

What do managers want?

So let’s get back to Stephen’s concern about writing technical information for his boss.

 

Managers typically don’t have the time to read detailed reports or procedures. That’s why business reports have an ‘executive summary’ – something that busy managers can read for a high-level overview of the subject.

 

If Stephen’s boss doesn’t have any technical background, it’s likely that he simply doesn’t want or need technical explanations most of the time. His primary job is to manage the team and the work the team does. The technicians’ job is to do the technical stuff.

 

And this point is key: What precisely do managers have to know to get their jobs done? And how can you make their jobs easier by what you write?

 

Start with THINKing

To begin with, think about why you’re writing to your boss about the system error (or any other technical problem).

 

This goes right back to the THINK stage of the TASTE writing process where you list:

·      Your purpose for writing

·      The action the reader needs to take

·      The details that will support your purpose and enable the reader to act

 

Here’s my best guess for Stephen’s situation:

 

Sample purpose

Let’s say that your purpose is to inform your boss about the system error and what it will take to solve the problem. Another purpose might be to request permission to take certain action to solve the problem or to request resources to get it done.

 

Sample reader action

Based on the purposes above, your boss may need to approve your action and acquire the resources you’ve request. Or he may just need to be informed about what you’re doing.

 

Sample details 

Again, think about the kind of information your boss needs to do his/her job. It may not be as ‘technical’ and detailed as you think.

 

The details she/he needs most of the time might be as basic as

·      how the system error is affecting the company’s work

·      how long it will take to fix

·      what resources you and your team will need to fix it.

 

Still not sure what to do?

I suggest you talk with your boss to find out which type of information he needs to do his work. He may not want or need any technical explanations at all – which will make your writing job much easier.

 

Of course, if (s)he does ask for technical information, that’s another issue altogether – and one that we’ll have to consider another time.

 

Do you help writing about technical issues?

If you need to write technical stuff for tech ‘dummies’, send me some samples of your writing, and we’ll work on it together.

 

Copyright 2014 DeGolyer Associates Ltd |  Contact Deborah at:  writewithtaste@me.com