Part I: What Is Technical Writing?
By Patrick M. Kennedy
December, 2006, 07:30
Writers are now and then called upon to create technical documentation. The majority of us can do it, for sure, but for those unsure there are certain guidelines that lead to success. Effective pre-planning and keeping it concise are two of the keys to successful technical writing. Here, we provide an overview that will scratch the surface of the field.
|Express your love for technology with a little technical writing.|
Some of the elements to be considered include:
- Knowing the audience
- Understanding the final product or medium
- Setting the attitude and approach
- Writing style, choice of words, and clarity
- Knowing the purpose of the document and the level technical detail required
Begin by defining the audience or end users. Are they professionals who will be fundamentally familiar with the subject of the document? Is the reader an engineer, a manager, a technician, a student, or a high-end user? Will the document be used for training, programming, marketing, or for general information only? This is a factor that must be determined before the writing begins to settle on the technical depth, word choices, and attitude of the writing. It is also necessary so information is not written down to the professional, or over the head of the layperson.
Become familiar with the final products of technical writing, such as user guides, software manuals, hardware manuals, maintenance and repair manuals, testing guides, training material, standard operating procedures, and many others. As a technical writer, you may be asked to write web content, computer-based training, online help systems, or marketing material. Each of these final products has its own conventions and limitations the writer must be aware of before starting the assignment.
A good way to become familiar with the different types of technical documentation is to browse some of the high-tech websites of well-known companies. Look for the areas of the websites that contain support information. Notice that you can read the content in HTML and often download it as a PDF file.
Standard documentation is the most common final product and involves writing detail and explanation, including graphics and references. This usually includes complicated detail and the most important focus for the writer is to keep the detail well organized. Keeping the common chunks of information grouped together and in the proper order keeps the reader involved and better informed.
Web content must be brief, direct, and to the point with a minimum of words because it is viewed in a limited screen area. Much like advertising copy, the web page must sell itself at the first glance or the readers will jump to the next page at the click of a mouse.
Online help systems are a combination of the web page and the standard documentation copy. There is normally a great deal of detail, but it must be in brief and focused chunks. Each statement or paragraph must stand on its own because the normal process of moving from link to link in a Help File will force detachment from the previous paragraph; thus, it must speak for itself.
Marketing material for high-tech products must be a combination of all of the above with the over-riding aura of a sales pitch tying it all together. Photos and graphics are often a part of marketing materials. Write the copy so it stands on its own. Do not describe the colors because they are in the photo; do not go over the numbers because they are in the graph; but explain why the colors and numbers should be on the readerís desk or in their business.
When starting a new assignment, most writers are baffled by the definitions, word usage, and acronyms used by the developers or engineers. Compiling a list of definitions and acronyms for personal understanding is a good start, and more than likely, you will use the list when you create documentation.
As a technical writer, you are the reader's advocate. The quicker the reader comprehends the documentation, the more effective it is. Write specific rather than general information. Technical readers are usually interested in details such as facts, figures, conclusions, recommendations, and especially how to use the technology to achieve a specific outcome. The key here is to make it clear and to the point. Keep a tight focus.
Write in a clear style, keeping it simple and direct, expressing the point in a relaxed and professional manner. Avoid the passive voice like the plague. Action must be expressed directly rather than indirectly.
So there you have a broad overview. We'll have a look at some more of the elements particular to technical writing in the next edition of IN. 'Til then, take some time to become familiar with the various types of technical documentation. Your computer, printer, and cell phone all came with some sort of manual or user guide. See if you can identify the ideas here exemplified within that documentation.
Patrick M. Kennedy has been a professional writer/editor/graphic artist for 30 years. He has published a novel, short stories and poems, articles in magazines, and he contributes a regular lighthearted column to the Senior Wire News Service. Find more about his background, writing samples, and services at: www.abetterword.com