“Life is like a sewer. What you get out of it depends on what you put into it.”
As a technical writer, one thing I often request is access to the product — whether it’s a web site, application, device, tool, etc. — that I’m writing about. In order for me to write something about a product, I need to know what the product is, how it works, and how to use it.
Unlike, say, a novelist or a creative writer, technical writing topics usually do not originate from the writer, but from something or someone else, such as a process, procedure, or product. In order for the writer to produce a good, quality document, he or she must know about it — what it is, why it’s significant, what it looks like, how to use it, potential issues, and so on.
What happens, however, when the only resource you have is someone else’s description? Moreso, what happens when that person is (by his or her own admission) not a writer? (There’s a reason why this person gave you this project in the first place.) I recently worked on a small side project that reminded me just how important this is. Granted, it was only a small and minor project, but it did remind me about just how critical it is for a writer to understand the subject.
Imagine the following situation: you need to add more windshield washer fluid to your car. You open the hood and see different caps. You know there are caps for washer fluid, engine coolant, oil, and so on. However, they are not clearly marked (as far as you can see), and you don’t know which one is which. Opening the wrong cap and filling it with the wrong fluid will damage your car. You call a friend who tells you to look for a plastic reservoir filled with blue liquid. Trouble is, there are two of them (one is washer fluid, the other is coolant). Your friend tells you to look for something that looks like a windshield on the cap. Okay, you see something that looks like it might be a window with a wiper going across it. That’s it.
Sound frustrating? These are the kinds of situations that technical writers and communicators deal with regularly and on a much larger scale. In order to write a technical document, the writer must have a source of good data — whether it’s hands-on experience, pictures, data graphs, good descriptions, etc. — in order to write a quality document. A bad or inaccurate source of data will often result in a bad document.
Developers, coders, and data professionals have a name for this kind of situation: garbage in, garbage out. In order for data to be processed into information (I won’t get into it now, but there is a difference between data and information — that’s another topic for another time), you need to have good data to start. Bad data results in bad and inaccurate information.
Writers cannot read minds. Unless a subject matter expert (SME) can properly convey his or her idea (and it almost never happens on the first go-around), it might take several iterations and lots of SME-writer interaction before the draft is correct.
Professional chefs have a term for ensuring everything is set up and in place before cooking: mise en place (pronounced “MEES-in-plahs”). While the technology sector does not use the same terminology, the principle still applies: make sure things are in place and ideas are properly conveyed before information processing (including documentation) can occur. Otherwise, trash at the beginning of the process will likely result in trash at the end.