Presents

Practical

Specification and Technical Writing

for Engineers & Technical Professionals

Revision 4

Web Site: http://idc-online.com

E-mail: idc@idc-online.com

Copyright All rights to this publication, associated software and workshop are reserved. No part of this publication or associated software may be copied, reproduced, transmitted or stored in any form or by any means (including electronic, mechanical, photocopying, recording or otherwise) without prior written permission of IDC Technologies.

Disclaimer Whilst all reasonable care has been taken to ensure that the descriptions, opinions, programs, listings, software and diagrams are accurate and workable, IDC Technologies do not accept any legal responsibility or liability to any person, organization or other entity for any direct loss, consequential loss or damage, however caused, that may be suffered as a result of the use of this publication or the associated workshop and software.

In case of any uncertainty, we recommend that you contact IDC Technologies for clarification or assistance.

Trademarks All terms noted in this publication that are believed to be registered trademarks or trademarks are listed below:

IBM, XT and AT are registered trademarks of International Business Machines Corporation.

Microsoft, MS-DOS and Windows are registered trademarks of Microsoft Corporation.

Acknowledgements IDC Technologies expresses its sincere thanks to all those engineers and technicians on our training workshops who freely made available their expertise in preparing this manual.

Who is IDC Technologies? IDC Technologies is a specialist in the field of industrial communications, telecommunications, automation and control and has been providing high quality training for more than six years on an international basis from offices around the world.

IDC consists of an enthusiastic team of professional engineers and support staff who are committed to providing the highest quality in their consulting and training services.

The Benefits to you of Technical Training Today The technological world today presents tremendous challenges to engineers, scientists and technicians in keeping up to date and taking advantage of the latest developments in the key technology areas.

• The immediate benefits of attending IDC workshops are:

• Gain practical hands-on experience

• Enhance your expertise and credibility

• Save $$$s for your company

• Obtain state of the art knowledge for your company

• Learn new approaches to troubleshooting

• Improve your future career prospects

The IDC Approach to Training All workshops have been carefully structured to ensure that attendees gain maximum benefits. A combination of carefully designed training software, hardware and well written documentation, together with multimedia techniques ensure that the workshops are presented in an interesting, stimulating and logical fashion.

IDC has structured a number of workshops to cover the major areas of technology. These courses are presented by instructors who are experts in their fields, and have been attended by thousands of engineers, technicians and scientists world-wide (over 11,000 in the past two years), who have given excellent reviews. The IDC team of professional engineers is constantly reviewing the courses and talking to industry leaders in these fields, thus keeping the workshops topical and up to date.

Technical Training Workshops IDC is continually developing high quality state of the art workshops aimed at assisting engineers, technicians and scientists. Current workshops include:

INSTRUMENTATION & CONTROL Practical Automation and Process Control using PLC’s Practical Data Acquisition using Personal Computers and Standalone Systems Practical On-line Analytical Instrumentation for Engineers and Technicians Practical Flow Measurement for Engineers and Technicians Practical Intrinsic Safety for Engineers and Technicians Practical Safety Instrumentation and Shut-down Systems for Industry Practical Process Control for Engineers and Technicians Practical Programming for Industrial Control – using (IEC 1131-3;OPC) Practical SCADA Systems for Industry Practical Boiler Control and Instrumentation for Engineers and Technicians Practical Process Instrumentation for Engineers and Technicians Practical Motion Control for Engineers and Technicians Practical Communications, SCADA & PLC’s for Managers

COMMUNICATIONS Practical Data Communications for Engineers and Technicians Practical Essentials of SNMP Network Management Practical FieldBus and Device Networks for Engineers and Technicians Practical Industrial Communication Protocols Practical Fibre Optics for Engineers and Technicians Practical Industrial Networking for Engineers and Technicians Practical TCP/IP & Ethernet Networking for Industry Practical Telecommunications for Engineers and Technicians Practical Radio & Telemetry Systems for Industry Practical Local Area Networks for Engineers and Technicians Practical Mobile Radio Systems for Industry

ELECTRICAL Practical Power Systems Protection for Engineers and Technicians Practical High Voltage Safety Operating Procedures for Engineers & Technicians Practical Solutions to Power Quality Problems for Engineers and Technicians Practical Communications and Automation for Electrical Networks Practical Power Distribution Practical Variable Speed Drives for Instrumentation and Control Systems

PROJECT & FINANCIAL MANAGEMENT Practical Project Management for Engineers and Technicians Practical Financial Management and Project Investment Analysis How to Manage Consultants

MECHANICAL ENGINEERING Practical Boiler Plant Operation and Management for Engineers and Technicians Practical Centrifugal Pumps – Efficient use for Safety & Reliability

ELECTRONICS Practical Digital Signal Processing Systems for Engineers and Technicians Practical Industrial Electronics Workshop Practical Image Processing and Applications Practical EMC and EMI Control for Engineers and Technicians

INFORMATION TECHNOLOGY Personal Computer & Network Security (Protect from Hackers, Crackers & Viruses) Practical Guide to MCSE Certification Practical Application Development for Web Based SCADA

Comprehensive Training Materials

Workshop Documentation

All IDC workshops are fully documented with complete reference materials including comprehensive manuals and practical reference guides.

Software Relevant software is supplied with most workshops. The software consists of demonstration programs which illustrate the basic theory as well as the more difficult concepts of the workshop.

Hands-On Approach to Training The IDC engineers have developed the workshops based on the practical consulting expertise that has been built up over the years in various specialist areas. The objective of training today is to gain knowledge and experience in the latest developments in technology through cost effective methods. The investment in training made by companies and individuals is growing each year as the need to keep topical and up to date in the industry which they are operating is recognized. As a result, the IDC instructors place particular emphasis on the practical hands-on aspect of the workshops presented.

On-Site Workshops In addition to the quality of workshops which IDC presents on a world-wide basis, all IDC courses are also available for on-site (in-house) presentation at our clients’ premises.

On-site training is a cost effective method of training for companies with many delegates to train in a particular area. Organizations can save valuable training $$$’s by holding courses on-site, where costs are significantly less. Other benefits are IDC’s ability to focus on particular systems and equipment so that attendees obtain only the greatest benefits from the training.

All on-site workshops are tailored to meet with clients training requirements and courses can be presented at beginners, intermediate or advanced levels based on the knowledge and experience of delegates in attendance. Specific areas of interest to the client can also be covered in more detail.

Our external workshops are planned well in advance and you should contact us as early as possible if you require on-site/customized training. While we will always endeavor to meet your timetable preferences, two to three months notice is preferable in order to successfully fulfil your requirements.

Please don’t hesitate to contact us if you would like to discuss your training needs.

Customized Training In addition to standard on-site training, IDC specializes in customized courses to meet client training specifications. IDC has the necessary engineering and training expertise and resources to work closely with clients in preparing and presenting specialized courses.

These courses may comprise a combination of all IDC courses along with additional topics and subjects that are required. The benefits to companies in using training are reflected in the increased efficiency of their operations and equipment.

Training Contracts IDC also specializes in establishing training contracts with companies who require ongoing training for their employees. These contracts can be established over a given period of time and special fees are negotiated with clients based on their requirements. Where possible, IDC will also adapt courses to satisfy your training budget.

References from various international companies to whom IDC is contracted to provide on-going technical training are available on request.

Some of the thousands of Companies world-wide that have supported and benefited from IDC workshops are: Alcoa, Allen-Bradley, Altona Petrochemical, Aluminum Company of America, AMC Mineral Sands, Amgen, Arco Oil and Gas, Argyle Diamond Mine, Associated Pulp and Paper Mill, Bailey Controls, Bechtel, BHP Engineering, Caltex Refining, Canon, Chevron, Coca-Cola, Colgate-Palmolive, Conoco Inc, Dow Chemical, ESKOM, Exxon, Ford, Gillette Company, Honda, Honeywell, Kodak, Lever Brothers, McDonnell Douglas, Mobil, Modicon, Monsanto, Motorola, Nabisco, NASA, National Instruments, National Semi-Conductor, Omron Electric, Pacific Power, Pirelli Cables, Proctor and Gamble, Robert Bosch Corp, Siemens, Smith Kline Beecham, Square D, Texaco, Varian, Warner Lambert, Woodside Offshore Petroleum, Zener Electric

Table of contents 01 Introduction 01 1.0 Introduction 03 1.1 What is technical writing? What makes it unique? 06 1.2 Objectives of technical writing (ABC's of writing) 08 1.2.1 Accuracy 08 1.2.2 Brevity 08 1.2.3 Clarity 08 1.3 Categories of readers 09 1.3.1 Skilled/expert/specialist 09 1.3.2 Decision-maker 10 1.3.3 Technician/operator 10 1.3.4 General reader or non specialist 11 1.4 Effective communication 12 1.5 Expressing versus impressing 14 02 Development process 17 2.1 Preparing to write 19 2.1.1 Establish the writing objective 19 2.1.2 Identify your readers 19 2.1.3 Perform research 20 2.2 Organizing the writing 27 2.2.1 The writing process 27 2.2.2 Methods of development 30 2.2.3 Document outlining 35 2.2.4 Idea generators 38 2.2.5 Writing the rough draft 42 2.2.6 Editing and revision 42 2.2.7 Proofreading 44

03 Language and words 47 3.0 Readability 49 3.1 Clarifying the writing 49 3.2 Choice of vocabulary 55 3.3 Simplifying the writing 77

04 The elements of technical writing 81 4.0 The elements of technical writing 83 4.1 Technical definitions 83 4.1.1 Informal definition 83 4.1.2 Formal definition 83 4.1.3 Extended definition 84 4.2 Technical descriptions 84 4.2.1 Description of a mechanism 85 4.2.2 Process for writing a description of a mechanism 85 4.2.3 Description of a process 88 4.3 Technical instructions 91 4.3.1 A technical instruction is made up of three elements 91 4.3.2 Technical instruction checklist 91 4.3.3 Outline for instruction sheet 92 05 Formats of technical writing 95 5.0 Types of technical reports 97 5.1 Formal report 98 5.1.1 Title Page 99 5.1.2 Table of Contents 101 5.1.3 List of Illustrations 102 5.1.4 Executive summary 102 5.1.5 Introduction 104 5.1.6 Min Body 106 5.1.7 Conclusion 109 5.1.8 Recommendations 110 5.1.9 References/bibliography 116 5.1.10 Appendices 118 5.1.11 Glossary 119 5.1.12 Other sections 120 5.2 Technical memo report 133 5.2.1 Types of reports 135 5.2.2 Technical background (lab) report 138 5.3 Other technical documentation 140 5.3.1 Technical proposal 140 5.3.2 Technical manuals (user and maintenance) 142 5.3.3 Journal article 145

06 Design specifications 153 6.0 Specifications and design 155 6.1 Design process 156 6.1.1 Flow chart of the design process 156 6.1.2 Understanding the problem and the development of engineering specifications 159

07 Specification writing 177 7.0 Introduction 179 7.1 Fundamentals of specification writing 181 7.2 Planning to write the specification 182 7.3 Preparing the specification 183 7.3.1 Customer 183 7.3.2 Market 183 7.3.3 Risk 183 7.3.4 Product 183 7.3.5 Scope 184 7.4 Specification database 184 7.4.1 Basic specification information 184 7.4.2 Supporting information 185 7.4.3 Organizing input from different specialists and sources 185 7.5 Structure of technical specifications 188 7.5.1 Government specifications 188 7.6 Specifications and contracts 210 7.6.1 Preliminary specifications 210 7.6.2 Using the specification during the bidding phase and

in securing a contractor 210 7.6.3 Using the specification as contract 211 7.6.4 Using the specification as instruction manual 211 7.6.5 Using the specification to monitor progress 212 7.6.6 Using the specification as review checklist 212 7.7 Checking the specification 215

7.7.1 Functional language correctness 215 7.7.2 Syntactic ambiguities 216 7.7.3 Theory 217 7.7.4 Prototypes 217 7.7.5 Realistic specifications 218 7.7.6 Compliance test 218 7.7.7 Evaluation criteria 219 7.7.8 Editing the specification 219 7.7.9 Presentation 219

7.8 Types of specifications 222 7.8.1 Government specifications and standards 222 7.8.2 Industry standards 222 7.8.3 Performance (output) specifications 222 7.8.4 Design specifications 223 7.8.5 Cancelled specifications 223 7.8.6 Creating a specification template 223 7.9 Writing the specification 226 7.9.1 Time and cost framework 226 7.9.2 Collaboration with other purchasers 227 7.9.3 Using consultants and specialists 227 7.9.4 Consistency in writing the specification 228 7.9.5 Liaison with industry 228 7.9.6 Specific and non-specific requirements 228 7.9.7 Tiering of specifications 229 7.9.8 Vetting the specification 229 7.9.9 Reviewing specifications 230 7.9.10 Constructive changes 231 7.9.11 Errors in specifications 231 7.9.12 Grammatical errors 232 7.9.13 Warranties 232 7.9.14 Tolerances 232 7.9.15 Specification approval and authorization 233 7.9.16 Hazardous materials 233 7.9.17 Conflicting requirements 233 7.9.18 Property disposal 234 7.9.19 Quantities 234 7.9.20 Professionalism 234 7.10 Do’s and don’ts of specification writing 242 7.11 Specification checklist 243 7.12 Summary 246

08 Final presentation 249 8.0 Appearance of the document 251 8.1 Text and design 252 8.1.1 Company logo 252 8.1.2 Generous use of white space 252 8.1.3 Titles, heading and sub-Headings 253 8.1.4 Listing 253 8.1.5 Contents and explanatory notes 254 8.1.6 Binding options 254 8.1.7 Stationery, color and typesetting 255 8.2 Visual aids 256 8.3 Most common formats of graphics 258 8.3.1 Line drawings 258 8.3.2 Tables 259 8.3.3 Pie charts 260 8.3.4 Bar graphs 261 8.3.5 Line graphs 262 8.3.6 Combination graph 263 8.3.7 Area graph 263 8.3.8 Pareto graph 264 8.3.9 Flowcharts/logic diagrams 265 8.3.10 Gantt charts 266 8.3.11 Schematics 266 8.3.12 Pictogram 267 8.3.13 Icon plots 267 8.4 Illustrations 268 8.4.1 Highlighting techniques 268 8.4.2 Column headings 269 8.4.3 Shading large areas of a chart 269 8.4.4 Posting values within a column 270 8.5 Tips for using illustrations/graphics 271 8.6 Transferring information from notes to graphics/graphics to notes 272

09 Oral presentation of technical documents 275 9.0 What is communication? 277 9.1 Motivation and attention 278 9.2 Preparing your presentation 279 9.2.1 Technical document 279 9.2.2 Goal 279 9.2.3 Central message 280 9.2.4 Body of presentation 281 9.2.5 Conclusion 281 9.2.6 Action 282 9.2.7 Introduction 282 9.2.8 Elements of an oral presentation 283 9.2.9 Preparation tips 283 9.3 Make a positive impact 284 9.3.1 Body language type 285 9.3.2 Appearance 285 9.3.3 Gestures and movement (posture and stance) 286 9.3.4 Eye contact 286 9.3.5 Facial expression 287 9.3.6 Style of speaking 287 9.3.7 Voice quality 287 9.4 Use presentation aids effectively 288 9.4.1 What are presentation aids? 288 9.4.2 Visual aids should support not dominate your presentation 288 9.4.3 Types of visual aid equipment 289 9.4.4 Use of visual aids 289 9.4.5 Design and layout guidelines 298 9.5 Maximizing delivery 299 9.5.1 Group discussions 299 9.5.2 Managing question and answer sessions effectively 300 9.5.3 Short talk guidelines - impromptu sessions 303 9.5.4 Handling difficult situations 304 9.6 In summary 306

List of Tables and Figures Bibliography Appendix A: Cause and effect method Appendix B: Example of a web specification

01 Introduction to technical writing

Technical writing

Version 4 2

01: Introduction to technical writing

Version 4 3

1.0 Introduction "In science, one tries to tell people, in such a way as to be understood by everyone, something that no one ever knew before". (Paul Dirac)

Engineers and technicians trained for many years to become fluent in their field of expertise, which does not necessarily include the art of writing. Writing, at the best of times, constitutes a boring, dull, difficult and unfamiliar chore for the technical person.

Writing takes place in the absence of the reader, and should therefore leave no scope for misunderstanding. To bridge this divide, the writer or author needs to be careful to write with the intended audience in mind, and to provide all the help needed to make sense of the written word. Complex writing results in a waste of time, lost contracts and alienated customers, in other words, a loss of money.

The rapid change in technology results in illiteracy in the technological field. Technical writing is an effective way to help customers understand new products and developments.

The writer must anticipate the needs of readers, and must supply whatever context needed to understand the meaning, relevance and importance of what is written. The goal of writing is to help the readers understand something they did not understand before they began to read the document. What goes into a report or document should be determined not by what one knows about the subject, but by what the prospective audience needs to know in a particular instance.

Technical writing

Version 4 4

Books, reports, memos, articles - whatever the type of communication – convey information. We read to learn or to do. It helps us to think, to reason, to believe, to plan and to design. It answers questions, explains matters and assists in understanding. Writing allows us to document history, facts, science, actions and figures. It offers insight into company policies, procedures and future plans. We write and read with the objective to find information, to give information or to request information. Good writing will convince, persuade or invite action. Technical writing is our link with management, colleagues, customers and the wider public.

The main purpose of this course is to demonstrate ways of assembling and constructing facts, ideas, arguments and instructions, translating it into skilful communication. The aim is to develop principles of technical writing that give it a logical base, appealing to both the technical and/or non-technical reader. This writing course encourages writers to be efficient and logical in their use of words, ensuring that the purpose of each component is understood and achieved.

The course will assist the untrained writer in understanding and applying the basics of writing, utilizing the gained knowledge to write technical documents. It serves to improve the writing skills of capable writers who need to refresh their writing strategies. Numerous companies employ professional Technical Writers. Appropriate writing methodology could positively affect your career advancement. By improving your proficiency in writing, you not only develop your own communication skills, but also enhance your social interaction with others in your company. This manual is also intended to serve as a valuable book of reference in your company and personal library.

Your proficiency in writing is determined by your answers to the following questions:

• What is the purpose or goal for writing the document or report?

• Who will be the audience of the document?

• Do you think as your readers do?

• Are you familiar with the basics of writing such grammar, spelling and punctuation?

• Do you know the difference between active and passive sentence construction?

• Do you address your audience directly?

• Can you communicate in a clear, understandable, simple language?

• Do you brainstorm and plan before you write?

• Is your document organized in a logical sequence, grouped under subject headings?

• Does your document or report contain a summary?

• Do you review and edit what you have written?

• Can you communicate persuasively?

• Do you refer to other similar documents to establish a model or format that could be applied to your specific document?

01: Introduction to technical writing

Version 4 5

• Have you familiarized yourself with styles, formats and wording used by your organization or company?

In this course we will cover aspects such as:

• Common types of technical reports

• Specification writing

• Special format items such as lists and headings

• Simple techniques for incorporating graphics into reports

• Techniques for producing professional-looking final documents

• Basic grammar

• Spelling and sentence structure

• Punctuation

• Referencing and citations

• Writing as a team

• Oral presentations

• Editing and revising

Technical writing

Version 4 6

1.1 What is technical writing? What makes it unique?

"In theory, there is no difference between theory and practice. But, in practice, there is." (Jan L A van de Snepscheut).

Technical writing encompasses the aspects of writing in the world of science, technology and business. It forms part of the regular work of scientists, doctors, computer specialists, engineers and government officials. Technical communication therefore implies the writing skills needed in any technically oriented professional job, and can be about any technical topic. It also builds on other writing.

"Technical" refers to knowledge that is not widespread or common, and is the territory of experts and specialists in their respective fields.

Do not fall into the trap of assuming that technical writing is not creative writing. It is highly creative, within a set framework. The only exception is possibly a pre-set questionnaire form.

One way to distinguish technical writing is to compare it to other types of writing. Once we have done this, the definition of technical writing becomes clear.

Fiction Expressive writing

Persuasive writing

Includes poetry, novels and short stories

Example : diary entries

Example : editorials

Writing is imaginative Emotional response to a personal experience

The goal is to influence your audience towards conduct or attitude change

Table 1.1

‘Other’ writing

Technical writing is different. It requires give and take. When you write a memo or report, you expect a reaction. When you write instructions, you expect that someone will follow the steps outlined. In other types of writing you do not necessarily receive any immediate feedback.

Technical writing creates action. When you write successful technical correspondence, the reader responds. Consumers act by following instruction manuals. Management implements suggestions and bases decision-making on information submitted. Specialists, technical staff, researchers, students and the general public use technical documents (eg journals, articles, and books) as reference material.

01: Introduction to technical writing

Version 4 7

The targeted audience, the receiver of the information, is a key factor in technical communications. Technical communicators are transmitting technical information to readers by adapting it to their needs, their level of understanding and background. The challenge is to translate a highly technical subject in an understandable way to a novice (non-specialist).

Whereas ‘other’ writing can be short-lived or become classics (hardly ever changing in terms of content or style), ever-changing technology and progress dictate revisions and updating of technical documents on a continuous basis.

Technical writing is often not limited to one author, but involves multiple writers, specialists and various sources of information. Due to its complexity, it requires the input of editors, referees and moderators.

More often than not, technical writing has a limited readership and books of this nature have a low turnover. Technical books are therefore also relatively expensive.

Technical writing

Version 4 8

1.2 Objectives of technical writing (ABCs of writing) 1.2.1 Accuracy

"Make everything as simple as possible, but not simpler". (Albert Einstein)

Precision and accuracy will enable the reader to follow and understand a piece of technical information without mental question marks. To be precise and accurate, means that irrelevant material must be discarded, ambiguous statements should be clarified and expressions and sentences should be simple and in sequence. The language used must be grammatically and textually correct. The writer must not be biased and must document all relevant facts. The technical writer writes as observer, researcher or participant, or a combination of these. Since technical writing is normally based on existing information, the sources must be quoted.

1.2.2 Brevity "Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away". (Antoine de Saint Exupery)

The writing must be brief and concise, to the point. Lengthy and unnecessary writing results in loss of time and therefore money, on the part of the writer and the reader. Concise writing is more appealing to the writer. Only the information that is required by the reader to accomplish his goal must be recorded. Short paragraphs, sentences and words makes reading and following the context easier. Lengthy documents wrapped in superfluous information are bound to be boring and will detract from the message.

1.2.3 Clarity "Logic is in the eye of the logician". (Gloria Steinem)

Your writing should be easy to read and understand. The information must be specific and quantified. It should leave no place for misunderstanding. Follow a logical sequence of events. Badly organized writing will result in a loss of audience. Use familiar words and expressions. Guard however against inappropriate jargon, language only understood by a selected few people in a specific company or field of expertise.

International Marketing Nightmare

The name Coca-Cola in China was first rendered as Ke-kou-ke-la. Unfortunately, the Coke company did not discover until after thousands of signs had been printed that the phrase means "bite the wax tadpole" or "female horse stuffed with wax" depending on the dialect. Coke then researched 40,000 Chinese characters and found a close phonetic equivalent, "ko-kou-ko-le," which can be loosely translated as "happiness in the mouth."

01: Introduction to technical writing

Version 4 9

1.3 Categories of readers "Why don't you write books people can read?" (Nora Joyce)

When you write a report, instruction or memo, someone reads it. That individual/group of readers is known as the audience. A primary difference between technical writing and other types of writing is the importance of the audience. The audience, or reader, is the determining factor when writing a technical report. The writer has to be precise in his/her writing, because the audience is not present to provide feedback or to ask questions. The reader is dependent on words, and does not have facial expressions, gestures, intonation and emphasis to rely on like in a personal encounter.

The audience for other types of writing (persuasive, fiction, etc) is not required to act after reading the text. When a technical document is submitted, the reader responds.

There are four main categories of readers:

• Skilled/expert/specialist category

• Decision maker category

• Technician/Operator category

• General reader (non specialist) category

1.3.1 Skilled/Expert/Specialist

These readers are analytical and logical in their thinking. They are detail-oriented and critical. In most cases even skeptical.

Experts are perfectionists in their field and well organized. They share your level of understanding. They prefer a direct, simplified form of writing. The expert looks at writing in an objective, conceptual and rational way. They need minimal, thorough and accurate information.

This category includes engineers, technicians, scientists, specialists, medical doctors.

Technical writing

Version 4 10

1.3.2 Decision-maker Decision-makers act on information and facts supplied by experts and technicians. They do not necessarily have sufficient insight or expert knowledge of the product or service.

These readers are action and result-oriented. They are competitive and assertive. They are receptive to options. They are disciplined in time management. They need the "bottom line" which makes the Executive Summary an essential feature of the report or writing. Since the managerial reader is not in your normal writing "loop" (field of expertise), you need to provide more background information. Explain the why, who, when and how.

In this category, you will find managers, executives, coaches, entrepreneurs and pilots.

1.3.3 Technician/Operator

Operators or technicians possess highly technical yet practical knowledge. They need to perform a specific task or achieve a certain result with the aid of documentation. They are action and task-oriented. They need to understand what they read as quickly and easily as possible. This kind of writing should address your reader in a direct and personal manner.

Technicians, operators and maintenance staff fall in this category.

01: Introduction to technical writing

Version 4 11

1.3.4 General reader or non specialist In this category, you deal with the layperson, normally the user, with little or no knowledge of the product or service. They do not have the necessary background or knowledge of your field of expertise. This person needs enough information to use the product or equipment to perform a specific task; to support or advocate a new product or service; or merely to satisfy their curiosity. These readers read material outside their own field of experience. They could be receptive to new ideas, impractical, probing or overly cautious. When writing for them in mind, be clear and concise. Mould your knowledge to their level of understanding, but ensure that you never write down to them. For the novice or beginner, you might need to supply important background, step-by-step instructions, or definitions of key words. Omit information that is not needed to achieve the desired result.

Technical writing

Version 4 12

1.4 Effective communication

"I choose a block of marble and chop off whatever I don't need". (Francois-Auguste Rodin)

Communication requires a sender and a recipient. The mission is accomplished if the message reaches the audience, the audience understands the message and the message provokes the required result (action, emotion, response, persuasion, etc).

There are various reasons for failed communication. A few of them are highlighted here, and will be discussed in detail in the following chapters.

Contents not appropriate:

Too much or too little information might confuse or irritate the reader. Only record the information that is needed by your audience for the specific purpose which is intended.

Writing style:

Sentence structure is important to avoid confusion and ambiguity. Write statements in a positive form. Use active verbs, which makes your writing more direct and immediate. Passive writing is not really suitable when writing for the non-specialist audience. Keep sentences short and clear. Paragraphs should be short and concise.

Word choice:

The words you use will set the tone of voice, and will either negatively or positively influence your reader. A glossary will assist in explaining technical terminology. Many words sound similar but have different meanings. Using the wrong word can have an undesirable effect.

Language:

The purpose of technical writing is not to impress; it is to express, to give information, technical data and facts. Avoid stuffy language and unfamiliar words.

Punctuation and spelling:

Incorrect punctuation can change the sentence structure and therefore the meaning of a sentence. There should be no spelling mistakes in your writing.

See

01: Introduction to technical writing

Version 4 13

Examples:

Examples (especially analogies) are excellent ways to explain statements. Make sure, however, that the examples fit the profile of the reader.

Structure of document:

The information in a document must be structured and organized. Sometimes the structure of the document should be changed to achieve the intended effect. Use conjunctions to allow for logical transition to the next phase or statement.

Purpose:

The introduction of your document should clearly state the topic, purpose and contents of your writing.

Graphics:

Simple and ample graphics and illustrations make your writing reader friendly.

References:

Cross-references make for easy and understandable reading, eg a manual with cross-reference or concordance, which makes reference and research easier.

Appearance:

Simplify your document with clear headings and sub-headings. Incorporate lists in table or column form to make the document easier to highlight certain aspects of the report. The typeface (font), ample margins and shorter lines make the document attractive and easier to read.

Keep the reader in mind:

When you receive a technical document, you have a certain expectation as to what it should look like and what information it should contain. Ensure that you are familiar with what the reader would expect to find in the document.

Self-improvement:

Read documents, reports and books that are similar to the ones you are planning to write. Ensure that you have access to reputable writing guides, good dictionaries, style manuals and usage books.

Stationery:

The appearance of your writing is very important. Give attention to logo, color, font, weight, margins and white space.

Technical writing

Version 4 14

1.5 Expressing versus impressing Many professionals face the dilemma of whether to impress their readers, or to express ideas that convey information. As is the case with any written communication, the contents should be determined not by what you know about the subject but what your targeted audience needs to know, in a language that they will understand.

A good rule to follow is to write to express and to think proverbial.

When writing for the non-specialist, avoid the mistaken belief that your audience is as interested in your topic as your are (also called the "specialist's fallacy"). Some writers underestimate their own accomplishments. Do not assume that all your readers are specialists in the subject matter and that they will read every word. If you understand the contents, it does not mean that all your readers will understand it.

Avoid documents that are too long and contain too much technical detail or specialized terms (technical jargon). Specify action requests and highlight key points. List the contents to enable your reader to find headings and topics easily. Put any information that is additional to the specific purpose of your writing in an appendix for those who might be interested in it. A document that does not answer to this could be misunderstood, misread or not read at all. This could lead to serious mistakes, loss of productivity, mistrust and even legal action.

01: Introduction to technical writing

Version 4 15

Figure 1.1 Expressing versus impressing

A plumber has used hydrochloric acid to clear some clogged pipes. The process worked quickly and cleared the drain. The plumber wrote to a research organization to tell them of the expedient method and ask for their appraisal.

*

Agent 1 wrote back as follows: “The efficacy of hydrochloric acid is indisputable, but the highly corrosive residue is incompatible with metallic permanence”.

*

Highly encouraged, the plumber wrote back that he was glad they agreed with this use of the acid.

*

Concerned about the apparent failure in communication, Agent 2 wrote back as follows:

“We cannot assume direct or indirect responsibility for the possible production of toxic and highly noxious residue obtained from the hydrochloric acid and ascertain that you should examine alternative procedures”.

*

Encouraged by the second letter and the enthusiasm of the agency, the plumber wrote back that the acid was working great and that they should recommend its universal use in freeing clogged plumbing.

*

Technical writing

Version 4 16

Consider figure 1.1 and complete the exercise below:

1. What would you say is the correct way to convey information?

__________________________________________________________

2. Is the first written communication "expressive" or "impressive" writing?

__________________________________________________________

3. Substantiate your answer:

__________________________________________________________

__________________________________________________________

__________________________________________________________

4. Paragraph 2 is an example of "impressive" writing. Rewrite the message in a clear, concise way.

__________________________________________________________

__________________________________________________________

__________________________________________________________

__________________________________________________________

__________________________________________________________

__________________________________________________________

__________________________________________________________

__________________________________________________________

__________________________________________________________

__________________________________________________________