Why is Technical Writing so Difficult?

Technical writers are a rare breed. To be successful in this profession, you have to be patient, know how to communicate, and, last but not least, understand technical concepts. These tough demands have been the inspiration for this article, the third and final, in what we like to call our technical writing “rant topics.” See the first two in the triptych, “What’s Wrong with the Passive Voice” and “Why is Consistency Important.”

So, what makes technical writing such a challenge?    

Classical Rhetoric
You don’t need to be a Sophist to be a technical writer. In fact, you probably won’t be too successful. Effective technical writing is short and concise. No balanced, nuanced sentences, no metaphors, no persuasion, and no fluff. When I asked one of our technical writers what the most challenging part of technical writing was, without hesitation she answered, “It’s dry.” Although this may seem a bit blunt, technical writing ensures the message is communicated clearly. Here’s a poor writing example taken from a manual describing how to install a hard disk drive, “Heading up the upper cover to turn over to rise.” Huh? This sentence seems to have been thrown into an online translator and converted to English. Too bad anyone who has a third grade understanding of the English language knows this sentence is terrible. Technical writing must eliminate all uncertainty and ambiguity. Let’s face it: When do people bother to look at a technical writing document? When they have a problem and need to fix it quickly. Did you sit down and read the user manual for your new car when you first got it? Probably not. The technical writer has one job to accomplish – make the material as simple and concise to understand as possible and easy to access (find).

Complexity of Material
Technical writing is just that – technical. Aside from writing, the most important part of the job is the ability to comprehend complex material so that you can explain it to others. Because your audience is potentially so broad, documents must be written in a way that the information can be easily understood by someone with any level of technical background. One of our newest technical writers, Heather Hauser (no slouch with a Ph.D. from GA Tech), can attest to this. When asked about one major difficulty she encountered in learning technical writing she responded, “. . . being given several pieces of information from different people and having to create meaning from the pieces so you can explain it to someone new.”

On the other hand, you have to be careful to remember your audience might not be as technical as you. We like to use the example for some of our very technical people who have high expectations of their readers, “will my 93 year old mother have any idea what you’re talking about?” We try not to use the phrase “dumb it down” but sometimes that’s exactly what you need to do. Again, to quote Dr. Hauser, “As a technical writer you must be able to think like someone else and put yourself in the shoes of someone who has no experience with the topic you are writing about.” Having technical knowledge and a willingness to learn technological concepts are very important if you want to become a technical writer. The first step in making a difficult concept easy to understand is to understand it yourself. You can’t explain anything to anyone if you don’t understand it.

Grammar Police
And then there’s the grammar problem.  Check out this example:

 

 

 

 

 

 

 

Run-on sentences, comma splices, misspellings: sorry, they’re not ok. Write poorly and your audience – even the engineers who hate writing – dismiss your work, even if it’s factually correct. For example, this excerpt was taken from a commercial air-conditioner user guide, “Do not blow the wind to animals and plants directly. It occasionally causes a bad influence for animals and platns [sic] to be excerpted.” Not only does this make absolutely no sense, but plants is misspelled. The instructions only seem to worsen as you continue through the document. Another direction advises users to “please do not put the one embarrassed because it gets wet under the air conditioner.” What? As technical writers we have to make sure our documents are error free and easily understood.

Look & Feel
People expect documentation to be functional and pretty. This means having a consistent format and design that is pleasing to the eye but also easy to navigate. Look at the following sample taken from the HDD Assemblies Elucidation (hard disk drive) manual referenced before:

Remember: simple, easy on the eye, easy to navigate.

Technical documentation needs to have a consistent format throughout. Simple things like all headers having the same font size and all figures being labeled the same way are very important and help readers navigate with ease. Each client may have a “corporate look” or strict guidelines as to what the page should look like. Regardless, the writer must make sure that the design and format are consistent and that they fit the content.

A great example are user guides for Apple products. Check out the one for the new iPad here. Notice how the layout is clean, consistent and also visually appealing.

Tools of the Trade
While we have commented before on the use of Word (No More Words in Word, Please), there are plenty of technical writing tools available. The project must determine the tool. We’ve talked about using a single source tool like AuthorIT for answering RFPs (RFP Nightmares. Had Enough?) because it works so well. In a forthcoming article, we’ll talk about creating HTML for developer documentation. The point is, the tool must be able to address the requirements of the deliverable. Word is perfectly acceptable to use for a memo or a short essay but it doesn’t handle large documents with lots of graphics. Adobe InDesign is a terrific tool for laying out a newsletter or data sheet. But why would you use it to create a large technical manual? The technical writer must know the tools available and have a level of competency in how to use them correctly.