As we all know, 'tech' is everywhere you look today – from i-pods to cell phones and Bluetooth, to digital video games, to complex computer systems, and even digital special effects at the movies. Technical writing is everywhere too, often embedded in the most casual e-mails and memos and the presentations that many of us have to create at work. Unfortunately, many of us are not as technically savvy in technical writing as we'd like to be. Good business writers without much technical writing training are more common today than writers with a lot of technical writing experience. We know how to write a clear business memo or a transition letter or a simple email. Most of us can create a simple PowerPoint presentation, but when it comes to handling really complex technical text, we get nervous. Yet more and more, especially with globalization, we find ourselves having to be technical writers in our professional communication, and we don't feel as comfortable creating this kind of material as we'd like.
If you don't have a technical degree or practical experience writing documentation and manuals for tech gadgets and suddenly you have to explain something technical to a colleague or to your supervisor in writing, what do you do? What's the best way to handle the technical writing that you may have to include in your documents? What pitfalls do you need to watch out for to avoid disaster and maybe even unpleasant embarrassment?
There are three major concepts to remember when you're dealing with technical copy. The first is your audience or your readers, the second is terminology, especially secondary terminology, and the third is visuals. Learn how to handle these three aspects effectively, and you'll avoid at least some the pitfalls that can await you. You'll be in a better position to handle a complex project or help a colleague when your team has a technical document to complete.
Always think of your audience first. Who is going to read your technical text? Will it be an engineer with a lot of background in the topic or your CEO who hasn't got a clue about technical terminology and only wants to know the big picture and the bottom line?
Once you know your primary readership, focus your material appropriately and include the detail that is necessary for a clear comprehension of any technical ideas or processes.. Write more in narrative style and explain, explain, explain, and then maybe just explain again. If your audience is a technical department, keep in mind that different departments regularly use their own technical phrases or acronyms for their own areas of expertise, and edit accordingly. Include more explanations and definitions and maybe a glossary, and avoid shorthand phrasing and references. On the other hand, if the document will only be circulated in your own department or division internally, you can be more concise and include some abbreviated phrasing that will most likely be recognized by everyone because they're familiar with the language on a daily basis.
Next, think terminology. Right along with the above advice about the audience is practical advice regarding the use of terminology. Most people who write technical documents know they have to explain the terms that reference any technical concepts and do so, although sometimes not as clearly as some readers might expect. However, the real problem occurs with secondary terminology pops its head up in a document. Secondary terminology is often ignored because few understand it, namely that the words or terms that you use to define primary terms you mention in a document are just as important, maybe even more important, than the original language.
Why is that? The answer is simple. If you are trying to learn a process or understand a complex technical concept, and come across a term that is key to that understanding, you don't want that term defined with another term that you have never heard of or is not defined anywhere. You want the secondary term also defined clearly, so you can understand the first term and then be able to do the task or learn the process. Forgetting to define secondary terminology is a common mistake in technical writing. The writer simply often assumes that you will understand the complex term that you're using to explain another complex term, but of course, you don't. You're immediately lost and can't follow the context.
So what's the solution to this confusion? Always check your document for terms you use to define other terms. Then make sure that the secondary terms are clearly explained or footnoted in language that a non-technical audience will understand. If you are preparing a document for an expert audience, always be aware that there may be readers that are NOT experts and make appropriate allowances either through easy-to-understand footnotes or a glossary of important secondary terms that are defined separately from the main document, but easily available to any reader who is not as well versed in the technology. In that way, a CFO, or a CEO, or an administrative staff member can review the same document without feeling out of touch with an important project or task.
Always review a technical document to make sure you're not defining an important term with another term that is vague or undefined. Also watch out for circular discussion that uses undefined terminology to explain concepts or processes, and avoid defining ANY term using only the original term. The goal of technical writing is clarity and more clarity. A technical term should always be precisely presented even when you think that clarity is not needed. Check again and then again to make sure. Doing so will save a lot of confusion, money, and sometimes even injury.
Finally, we come to an intriguing and useful aspect of technical writing – use of visuals. Visuals are wonderful adjuncts to text in technical writing because visuals can explain with a picture what it might take a writer 500 words to explain in text. However, it is also important to remember that visuals should never stand in isolation within a document. You must integrate each visual clearly and precisely into what you are discussing in the text. You must introduce a visual clearly, indicate its purpose precisely, present it with a caption that relates it to its purpose and the text, and then integrate the concept presented via the visual in the following text. Otherwise, a visual can be stuck in no man's land and have no significance. It will be ignored. The valuable information contained in the visual may be passed over, and the text that follows may not be clear either. A visual is a vital part of a technical piece of writing, not just an addendum that can be slapped on as an afterthought. Always review your document to see how your visuals interface with your text and review the placement of all visuals to make sure they add to the meaning of your document and not simply detract from it.
If you remember these three aspects of technical writing and use them as useful techniques for the technical writing you need to do on the job, your communication will be more precise and clearly communicated to technical and non-technical readers alike. A bonus will be that you will be seen as a good communicator by all your colleagues, and that reward will be a solid boost for your career.