By Lawrence “Lonnie” Brennan
You enter a building, walk through numerous doors, and never think about what the handles look like, which way to turn, how far to turn, how much pressure to apply—the door knobs and handles are in a way, invisible, transparent, irrelevant to your task at hand (get inside, move from room to room).
Your users, similarly, have a task to perform: a complex piece of equipment to assemble or test, and they are focused on the product and its components and connectivity. Giant sledge hammers, small eyeglass screwdrivers, torque wrenches, shims, brackets, and alignment tools are means to an end—get the product built accurately, consistently, in a rapid fashion, each and every time.
And what do we do? We cram details and verbiage into complex steps telling technicians and assemblers exactly how, when, and why to perform these steps. Why?
Why do we make users read? Why do we slow them down with peripheral information and distraction? Why do we assume they have no knowledge, no experience, and no context? Why do we produce documentation that has to be read, slogged through, understood, processed, followed, etc.?
A large portion of documentation exists because of poor designs or complex designs. If products were designed for manufacturability or ease of use, the integration of many parts would be as simple as square pegs in square holes, round pegs in round holes. With regret, a bracket can be mounted this way or that way, or flipped this way, or rotated that way. No color codes, indents, braille-like engravings are typically included in the design of a product. Documentation has to pick up the slack.
How can we make our documentation transparent? And what is transparent documentation?
Think in reverse: what is the least amount of information (text and graphics) that I can place on a screen or on paper that will convey the action required on the part of the user? Or, more simply, what can I do to approach invisible, transparent, or otherwise unobtrusive (lowest brainpower wattage drain) to guide a technician or assembler through the task at hand?
Transparency starts with thinking visually. More precisely, thinking about the task from the user’s point of view in all that we do. Transparency also requires us to be prepared to create simplified documentation, with simplified language, with simplified steps. Every word must be weighed for its usefulness. Every line in a drawing and every pixel in a photograph (almost every pixel) needs to be scrutinized, and should remain on the screen or page only if it propels the user forward, seamlessly, as a seemingly transparent guide through the assembly process.
Yes, this is the zen of technical writing: getting within your user’s mind, and feeding that mind only with what it needs, at a particular point in time, and convincing the user through graphics, layout, space, callouts, implied motions, and other methods that the documentation is easy to read.
Read that last sentence again. Note the simple use of the phrase “at a particular point in time.” That’s the secret to transparent documentation that we tend to ignore in Tech Writing 101: eliminating screen debris, instructional clutter, the weeds, the elements in our instructions which stop rapid progress, the words or visuals which shouldn’t be there, right now, because the information isn’t needed until a subsequent step, or not at all. If we spend more time weeding—eliminating excess information—our procedures will become lighter, friendlier, more transparent (more rapidly processed, seamlessly, with no slowdown in the express-reading lane of the user’s mind).
Transparent Graphics: Using Your Mind’s Eye
Can you put your mind’s eye up above the ceiling and have it look down at yourself? Seriously, can you see the top of your head? Your arms extended out on your desk, on your keyboard, on this magazine? Can you visualize the color of the desk from that angle? The rings on your left hand? Can you move that camera rapidly to your left and see your side view? Can you move it behind you, see the back of your head, your arms on the keyboard, your screen before you? Can you shift it now, pretending that you’re driving in your car down the highway, and move the camera all around your vehicle, always being able to rapidly view the angle of your car or truck or camel? Were you able to switch to riding a camel, and have that camera angle and visual come up quickly in your mind’s eye?
If you can move your mind’s camera, rapidly, and focus your mind on that which it would see, you are a visually gifted individual. If you’ve not done this, you too can achieve untold visual expertise with practice. Start slow, move that camera around. Don’t get frustrated. Move into it. Run the movie in your head.
Why would you do this? Don’t you hate it when you try to follow instructions but the graphics (artwork or photographs) are at the wrong angle from your point of assembly view? Or worse, when the orientation changes abruptly (shown from the left side when you were working on the right side, or shown from the back side, or across the table from where you sit, or flipped back and forth between this view and that view)? Each time the camera angle shifts abruptly, there’s a time lag, a processing lag within one’s mind that takes time (micro-seconds? seconds? a minute?) to figure out the orientation. During this processing lag, you’ve just gotten exposed: the user is now focused on the instructions, the visual, not the task. Your documentation is no longer transparent. It’s a wall. It’s slowing down progress. And once exposed, your documentation becomes an impediment to rapid process—the user must now actively process your documentation—they must think about it, slow down, consider it, pay attention to it, take time off the task to grope with it. Sounds counter-intuitive, huh?
Hiding from the mind’s acknowledgement that it must actively burn brain cells at high wattage to understand, interpret, and otherwise process your instructions is not easy at first, but it can be fun. Solutions are simple to find, and it starts with applying some of the basics you either were not exposed to in Tech Writing 101, or simply didn’t take away as strongly as you might have.
Let’s start with camera angles (graphics, illustrations): angles need to be chosen with extreme care and from the perspective of best, most consistent and natural use by the assembler or technician. We need to construct our graphics or take our photographs from the user’s perspective—from the user’s eyes. (And, yes, that might mean getting personal over someone’s shoulder, repeatedly. But that’s just part of the solution, deciding what to show and how to show it, ah, the fun is just beginning.)
Nothing turns off the user faster than having to struggle through a wall of words, or to read lines and lines of instructions. If you can use a photograph instead of a paragraph, do it. If you can grey-out most of a photograph and showcase/highlight just the items of interest, do it (de-couple the items being handled by the user from the previously installed items). If you can use a 3-D line drawing instead of a photograph, do it. If you can use a 2-D line drawing instead of a 3-D construct, consider doing it. Push to simplify the graphic to draw your user’s attention to the items of interest.
With this exercise, I am reminded of an art class in which one student depicted a female model through a highly-detailed line drawing of her eyes, using perhaps hundreds of fine lines in this area, then used just four or five lines to depict the remainder of the model’s entire body. The four or five lines confirmed gender and shape, while the fine detail of the eyes focused the viewer’s attention to the area of interest by the artist. (The teacher responded positively when the student explained, “I wanted to focus the viewer’s attention in one area. Did this not do that?”)
Side-clutter, irrelevant detail, graphic debris as we call it, might look nice, but if it detracts and causes even a momentary pause, a delay, a need on the part of the assembler to pause and interpret or otherwise process the item, you’ve failed: your document stopped the assemblers’ progress, made them slow down or stop. You’re no longer transparent. And on some level, now that you’re exposed for being an impediment to progress, it will be difficult if not impossible to resume your role as a transparent helper/guide/usher through the difficulties of a complex task.
Transparent Language
Are you up to the task of putting your mind’s eye into that of your user? If so, you’ll never look at another graphic, anywhere—on a subway wall, in a magazine, in a restaurant’s menu—in the way you did yesterday. Now it’s time to get back to the basics of technical writing 101, with a twist: make your language transparent.
Transparent language? Are you nuts? Well, not exactly transparent, we’ll use ink or pixels, but the goal is to make the language so simple, with the least amount of ink or pixels, that the meaning will transmit seamlessly to the instruction user, with no delays, no application of the brake pedal.
So we start with eliminating the wall of words, the basic “chunking” of steps down into sub-steps, etc. We’ve all done it. Often we find this “chunking” step to be the first step we must perform, repeatedly, on documentation provided by engineers. Those intelligent, thoughtful, detailed souls were forced to take one or two technical writing classes in engineering school. With confidence, they’ll happily pontificate endlessly on the need for a line, a bullet, a tense, a comma, or semicolon. Like the end user cares?
Let’s cut through this rabble quickly: put down the pens, take your hands off the keyboard, put down the pocket knives. Pick up the chainsaw. It’s time to cut down this forest.
Write Less, Say More
The best way to clean out is to throw out: if a word is not needed, don’t include it. Keep going back over your instructions. Omit needless words. And please use simplified language, or for the English language writers, use simplified English.
You’ve perhaps heard about the use of “simplified” English. The concept has been around for decades and some companies swear by it. It’s not so much that you write to a given audience’s comprehension level (small words, simplified noun/verb constructs), but rather that you use repetitive phrases consistently. Further, every word that you use in your instructions can only be used in only one manner. For example, use “bolt” as a noun only, and never as a verb “bolt x to y.” It’s either going to be used as a noun or a verb, but never both in the same documentation set. Keep it simple.
The best way to say goodbye to words is to use graphics, arrows, numbers, or pictures showing the action—application of grease or tightening a bolt clockwise—or otherwise replacing words with simplified graphics.
What’s the downside to transparent documentation? You’ll get laid off. Why? Everyone will look at the documentation, see that the instructions are simple, the task is easy to perform, both experienced and novice users have validated the task, and it’s just so usable. They’ll think: this is so easy to do, I wonder if we even need to have technical writers. It’s simple.
This may be a fair comment from the unenlightened, unappreciative minds of some in management; just be ready to supply some “before” examples to show what the instructions looked like in their first draft, and if that first draft came from a wall-of-words, excruciatingly detailed engineer’s draft, you’ll see your management reviewer respond (with head bobbing up and down), “O h, you got this from this, hmm, I see.”
Go forth, become transparent.
LAWRENCE “LONNIE” BRENNAN was president of the STC Boston Chapter (now STC New England) from 1997–1998. He is a senior technical writer at Analogic, in Peabody, MA, where he prepares user documentation and manufacturing instructions for the company’s high-energy inspection and medical systems.
