What is Technical Writing
It seems obvious, right? Technical writing is that magic art form that results in befuddling manuals that confuse when they should clarify, frustrate when they should delight, and exacerbate problems when they should be solving them. We all have experience with technical manuals, and the near-universal conclusion is: they stink. How is it that someone can spend so much time writing incomprehensible drivel and call it publish-ready content?
Imagine if you were to buy a fancy new toaster and the guide that came with it actually showed you how to use your new gadget? Or the 65” flat screen wonder of a TV set with the user manual that made it a joy to use your new toy? Or, if you work in a high-tech field yourself, the developer’s guide actually shows you how to build a working application using a vendor’s Application Programming Interface (API)?
The problem lies not in the technical teams that produce the whizz-bang gadgets we all own and love, but in the business’s commitment to good, clear documentation. Too often, documentation gets shoved down the list of important items as budgets get stretched too thinly across technical projects. It’s a funny paradox. On the one hand, everyone laments the lack of good manuals, but on the other, when allocating time and resources to produce them, project sponsors and managers balk at the effort and cost to deliver the one thing their customers rely on to use their gadgets.
If the problem is a dearth of quality documentation, where do all the poor quality semi-English guides and manuals come from? The all-too-often answer is: from developers and engineers. They’re the ones saddled with the additional work of producing not only quality products on time and under budget, but also the how-to manuals that accompany them. (More on this phenomenon in a separate article.) If it’s not the technician’s role to write documentation, you can be sure they don’t like it, because it shows!
What’s the solution? It’s simple: make the compelling case for documentation from project start all the way through to project end. Use subject matter experts if they’re available in house. If they’re not, do the due diligence to find the appropriate writer for the job. And keep that writer involved in all the key design, build, and test phases of the project. Give the writer access to developers, project managers, and, most critically, business analysts. They’re the key to the quality production of good manuals and guides.
In future articles, we’ll talk about what makes good technical writers and why you should treat them with the utmost respect. They may one day mean the difference between customer satisfaction and customer disdain.
