TW-E - Specification and Technical Writing for Engineers and Other Technical People

Researching and preparing technical documents, especially technical specifications, calls for much effort and time. This manual is designed to give you step by step guidance to writing these documents in a professional manner, working within a cost and time framework. This manual will demonstrate techniques to establishing more effective communication between technical and non-technical staff and foster skills relating to problem identification and solutions, plus enhancing skills in information seeking, research and organising collected data in a non-conflicting, unambiguous manner.

Download Chapter List

Table of Contents

Introduction to technical writing

1. Introduction to technical writing

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.

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?
• 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 revisin

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.

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.    

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.

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. 

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.

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.

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.

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.

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. 

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.

Figure 1.1

Expressing versus impressing

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.

__________________________________________________________

__________________________________________________________

__________________________________________________________

__________________________________________________________

__________________________________________________________

__________________________________________________________

__________________________________________________________

__________________________________________________________

__________________________________________________________

__________________________________________________________