Technical writing essentials

Topic status automatically displays here - do not remove.

Add me to your favorites! Bookmark this topic Print me! Print this topic

By Colin Ramsden, October 2006.

The tech writers most used writing tool What is the essence of being a technical writer? What does the technical writer need to know to perform their job? To best answer these questions, we need to understand what technical writing is, and who are technical writers.

What is technical writing?

Technical writing is just one form of non-fiction writing, and covers many different aspects of technical communication. Technical writing is:

accurate and honest,
clearly presented,
appropriately addressed to a targeted audience,
focussed yet informative,
useful and practical.

Technical writing is commonly accepted as the profession which produces the printed installation and operating documentation required for software and hardware products such as TVs, computers, printers, whitegoods, power tools, kitchenware, and electronic devices. In fact, any product which requires written operating instructions.

Actually, technical writing has very loosely defined boundaries, and includes a very broad spectrum of writing. Technical writing is prevalent in government and education institutional documentation, and in the bio-medical and research industries, in finance, banking and insurance, military, mining and manufacturing, legal and legislature, amongst others. For example, governments of both Federal, State, and Local produce volumous documentation which more than qualifies as technical documentation. The legal writing of lawyers and politicians is technical by nature, and equally qualifies as technical writing, as does medical research and mining and manufacturing industry reports. Yet, much of this is produced by people which do not consider themselves as 'Technical Writers'.

Who are technical writers?

Rather than narrow the term 'Technical Writer' down to a limited field of practicing writers of practical applications, I'd like to see an expanded view including, but not limited to, technical writers of legal, legislative, educational, training, research, institutional, corporate, manufacturing, mining, management, maintenance, support, marketing, sales, goods and services. These industries, fields, and endeavours each require varying levels of technical writing as an important and sometimes crucial aspect of many jobs.

The seven W's of effective technical writing

Now that we've broadly defined what technical writing is, and who could be a technical writer, it's time to examine the opening questions, "What is the essence of being a technical writer?" and "What does the technical writer need to know to perform their job?" There are several essential elements to effective technical writing:

1. What: Know what you're writing about—identify the subject matter

Firstly, the technical writer needs to know about the technical subject being written about, whatever that may be. The level of knowledge about the subject may be a general understanding, or very specific, dependent upon the level of technical detail required and appropriate for the intended audience of the writing.

2. Who: Know who you're writing to—identify the intended audience

Secondly, the technical writer needs to know who the intended audience of their communication is going to be, and understand what that particular audience already knows about the subject matter, so that the technical communication can be addressed and phrased appropriately to that audience. Note that the subtitle for this step is to know who you're writing to, not who you're writing for, so as to avoid the confusion between who is the intended recipient of your writing, versus who is paying you to write. After all, you are writing to people, and for pay.

3. Way: Know what they're trying to do—identify ways to help them achieve it

Thirdly, the technical writer needs to know what the intended audience is trying to do, or is most likely to achieve, with the information conveyed in the message, and what ways they might do so. This will allow you to determine the best way to structure the technical communication to help them achieve it.

4. Where: Know where information is needed—identify where to deliver it

Fourthly, the technical writer needs to know where the information is most likely to be needed, so that you'll know how how best to deliver the information where it is required. There are many possible means and locations of delivery, including verbal, visual, pre-event training, on-the-job training, printed, online, web-based, built-into user interfaces, stickers or notices in appropriate places or on appropriate things, CD's, DVD's, inside packaging, etc.

5. When: Know when information is required—identify when to make it available

Fifthly, the technical writer needs to know when the information is most likely to be needed, so that you'll know how how best to plan the technical communication to make the information available when it is required. Timing is crucial to successful delivery and reception. Information is only required when it's needed, not before or after. Imagine an illustration separated from the description of its parts by pages of text. If they are delivered separately, the result is the same. Delivered either too early or too late, relative information is impractical, unusable, thus easily forgotten and misplaced or lost.

6. Which: Know which information is required—identify which details to include or exclude

Sixthly, the technical writer needs to determine which information is necessary and useful, and which is not. Then you need to be able to write clearly and succinctly, in order to convey the message in a manner that is understandable and immediately useful to the target audience. When doing so, you need to remain focussed upon the message being conveyed, and not allow the writing to wander off-course by discussing an irrelevant topic or issue. Sifting through vast amounts of potentially conflicting information and clarifying which data is correct, then sorting, prioritizing and distilling the pertinent details is an essential element of good technical writing.

7. Why: Know why your technical writing is effective—identify the effective elements

Seventhly, the technical writer needs to constantly assess and reassess which elements are effectively improving their technical writing and communication, and which need attention and improvement. Without some means of feedback, the effectiveness of your communications can never be measured or assessed. Careful and constant re-evaluation can make the difference between effective or ineffective communications.

Link the following back to the definitions of technical writing listed earlier.

Note that all technical documentation has a purpose, and is only read to help achieve that purpose. If it's written for other reasons, it's not technical writing.

Sometimes, you may (like to) think that the purpose of technical writing is convey the facts. However, it is how people perceive what they can do with those facts, which can determine the quality and effectiveness of your technical writing. For example, take a moment to consider typical marketing "hype" writing, or political and military "spin-doctoring" using speeches and press releases. Consider the purposeful obfuscation of the wording in legal contracts along with financial or insurance terms and conditions. All these are factual, but do not necessarily qualify as good technical writing.

Output types: Printed, online,

Industries: Defence, aerospace, medical, insurance, civic and civil construction, maritime, energy, mining, transport, finance,