By Request: Issues in Technical Writing

Posted by mouthyb | Posted in , | Posted on 4:46 PM


One of the more startling things I've found as someone who has an English degree (the MFA is in nonfiction, and I've done a double shit ton* of free lance editing and technical writing), is that people seem to believe that writing and design are easy enough to relegate that task to people who may have no qualification for those tasks. It's not uncommon for professionals with no training in how to write manuals and/or brochures, design, editing and gauging an audience to be given a very small amount of time to do so.

The typical results are things like laughably bad manuals, design which is stuck somewhere in the 80s and steps which are impossible to do in the order suggested. Some professionals are, of course, capable of this kind of writing and design. However, it should not be assumed that someone who is incredibly competent in another field will automatically do a good job of design and technical writing.

Writing is actually a thing, and a demanding thing.

I have a friend who is facing that sort of problem right now; he's a more than just competent programmer, but his bosses have handed him the task of writing technical manuals for the servers he administers and for the projects whose frankencode he's been handed. (He says the code is awful.)

The problem which is currently frustrating him is fundamental to technical writing: where do you start assuming competence in an audience? This particular problem is actually something which is takes professionally trained writers years to get a clear sense of; the classes I've taught for composition and rhetoric dealt with this problem over four months, because it is incredibly difficult to clearly conceptualize and execute.

He's asked for some guidelines to consider. Without further ado, I give you my personal ones.

Bob** the Pragmatist's rules of thumb for estimating audience competence:

Is the audience the general public or some subsection of the general public?

If the audience is the general public, you'll be best served by over-explaining in a conversational tone. Think furniture assembly instructions: take the plug with the pink ring and match it to the plug on the back of your computer, near the bottom, which also has a pink ring. Good job!

If the audience is a subsection, particularly a technical or highly educated subsection of the general public, you can assume, whether it's true or not, access to technical jargon for the field and some task skipping.

Think of this as the PB&J rule. The hypothetical general public has never made a PB&J before. If you tell them to make a PB&J, but don't include instructions, they have no idea what you're talking about. And you can't just start with grab a loaf of bread, because they may never have made a sandwich. You have to figure out some way to describe sliced, presumably commercial bread to them so that they can locate it by sight. Same goes for the peanut butter, the jelly, and a butter knife to spread.

It's tempting to think of them as idiots at this point. Resist temptation; ignorance is not always stupidity, though I freely admit when I write for newspapers as a columnist the breadth of vocabulary I have to not use makes me want to head-desk myself unconscious. Assume, rather, that they are reading your manual because they want to understand. It's a rhetorical assumption, yes, but an effective one in many situations (obviously not one you're always obliged to take).

Now, if you're talking to people who have already made a PB&J about making a fancy fried banana PB&J (Uh-huh-huh, hip swing), the good news is that you don't have to explain what bread, peanut butter, jelly and a sandwich is. The bad news is that you have to explain any alterations to the pattern for making PB&J which they already know, and fold it into the explanation for how to make the sandwich so they do it in the right order. You must fry the bananas before assembling the sandwich, and you might want to include a description for what a fried banana looks like when it's done.

This means you still have to write the instructions, unfortunately, but instead of starting with locate bread in a grocery store by the presence of clear wrapping around a product which is soft and springy, sliced into sections a third of an inch wide with a distinctly darker edge around the outside and is not stored in a refrigerated section of the store, you can start with assembling bread, peanut butter, quince jelly, vegetable oil, one sliced and slightly green banana, a shallow frying pan large enough to fit the sandwich, a butter knife and a plate.

It makes for slightly less writing, though I've seen manuals which have a glossary. If the manual is online, hyperlinking can eliminate the need for a glossary.

Assuming that you are writing to your peers eliminates many of the definitional tasks, though it is generally best (unless you are talking to persons with broad experience or persons with extensive education) to limit the number of very large, very technical words if you can.

Based on these criteria, the assumption of basic competence includes the following criteria:

--They can read the language you're using (if not, add translations to other languages).
--They are either the general public or a subsection, both of which have different requirements for definition and tasks.
--They are best served by sequential ordering in tasks and are willing to do the tasks in the order suggested.
--They will try to find the answers to reasonable questions in your manual, which means you ought to try and anticipate those questions based on what an average person from their level of expertise might ask.***
--They will be best served by both an overview of steps and a detailed explanation of steps, including reminders of the final goal in addition to detail involved in steps. Even professionals need to be reminded of the end goal, especially in any manual which requires more than eight steps.
--They need the steps broken down based on changes in one of the following: a change in equipment used, a new sub-task (plugging something in versus sorting out the cables), a change in location, a change in type of task (importing libraries in code versus writing a function) so that they can effectively follow the stream of tasks which you assume they are trying to perform.

This is sort of technical writing light, and I'm pretty sure you can think of exceptions, but those are some of the fundamental assumptions of competence which tend to get used.

Oi there, buddy: when you read this, feel free to ask questions.

* That's the official measure of this blog-- a shit ton is more work than you can get done in a year.

** When I used to work at gas stations, I got tired of being aggressively hit on by men, especially since I was working alone. I chopped my hair and made a 'Bob' name tag. It only helped a little. Now I use Bob as a pseudonym during gaming: my current character's name is Lady Isobella Violetta Charmisa Margarite Coeur de Leon the Third, Bob for short.

*** Yeah, I know. That's a huge topic which is highly situational, so it's best if I offer you an example. Technical professionals are not going to ask what a computer is, but they are likely to ask what software version you're using because some functions are not covered in earlier versions. If they're programmers, they'll want to know why you're using that version, not their favorite version. The answer is NOT because I want to, that's why.

Comments (0)

Post a Comment