Return to Articles.
What is quality technical writing?
By Colin P Dunbar, MITCSAThere are many aspects which contribute to quality technical writing. And this article looks at some of the more basic aspects of quality technical writing. For easier reading the terms writing and writers will be used throughout this article.
After several years of personal observation, I believe the reason for poor technical writing to be two-fold: a) insufficient technical WRITING training, b) attitude of technical writers towards their occupation.
Unfortunately the industry are partly to blame for contributing to poor quality technical writing. The majority of writers are employed for their technical expertise. The finer, and more important aspects of the technical writing process are disregarded, or even ignored: the actual communication aspect is regarded as secondary.
Some points to improve the quality of technical writing:
In other forms of writing, and in particular in journalism, it is a fact that to be a writer one must be a READER. Reading books on the profession. Reading books on the subject being written about. This helps improve the overall quality of technical writing. How many writers read anything besides that which they write themselves?
John Bennett, a qualified fitter, now working as a technical writer says:
"It would certainly benefit an author to read up background information on a system or equipment he is writing about."
Writing instructions for air-conditioning equipment, John read extensively on air-conditioning systems, "Although I did not NEED to know everything I read, it did benefit me when I had to write the instructions."
So much has been said and written on specifications and synopses. I will not delve into the subject in the space of this article, except for one aspect: it would be a large step towards quality writing if the specification and synopsis where adhered to more closely by the writer.
A logical and practical example when writing to a specification and synopsis is this: Before and while writing a chapter or section, have the specification at your side, open at that chapter or section. That way it is there for immediate reference. Also have a copy of the synopsis at hand. "If in doubt, read the manual". What could be easier?
At a seminar some time ago Pete Morton said the following:
"Get involved with the specification and who knows... one day you might get around to reading the damn thing."
Here is also a prime example of what is mentioned earlier. Why don't writers read specifications? Agreeably, one cannot take in everything in the specification with one reading, but with the process of spaced repetition it is amazing how pieces of information stick in one's mind.
A basic and often ignored aspect of quality technical writing is writing for the END USER. It is the USER of the document that must understand what the writer has written. Not the person from whom the information was obtained, or the writer.
In some instances the writer will gather source information from an engineer or technician, and then write that information to the engineer's or technician's level of understanding. Possibly the user of the manual will be a person with a Standard 8 level of education. And in some cases the manual may be used by someone whose first language is not English.
Related to the previous point, and probably the most basic aspect of quality technical writing, is the fact that the writer must always write CLEARLY. Remember the end user!
John Kirkman, in the book TECHNICAL WRITING & PUBLICATION TECHNIQUES gives the following example on clear writing.
"Take care to avoid vague terms like SELECT (does that mean I have a choice?), REPLACE (does that mean ‘put back’ or ‘fit a new one’?) and CHECK (does that mean just ‘look at’ something, or ‘do’ something if a given condition is not being met?) A judge in a court of enquiry is unlikely to be sympathetic if you protest: "surely anyone knows that an instruction to ‘check that the valve is closed’ means he should close it if it is open!"
Probably the first rule in technical writing, yet still disregarded by many: WRITE CLEARLY! In most cases research takes the most time (and is the single most costly) in the production cycle of any document, yet many authors "cut corners" in their research.
Mike Austin, gives us the following:
"The basic research has two broad objectives; first, to assess what kind of people the readers are likely to be and what THEIR needs will be; second, to obtain the information on the equipment or process that will meet these needs."
Research, gathering of source material, CANNOT be regarded as a superficial aspect of the total documentation process. Austin's words may serve us well to remind us of the thoroughness required in the research process: "In his search for information a technical author needs to be something of a detective, a supersleuth, constantly probing, questioning and checking."
There are some basic questions the writer should ask at the onset of the project: a) Is the equipment available? When will the equipment be available? b) Who is the engineer, or technician to be contacted for information? c) Is there any documentation available which can assist in this project?
These three questions form the basis from where to start the research, but are by no means the only questions to ask. A practical and time-saving hint is to draw up a checklist of questions before commencing with the research.
When interviewing technical personnel, remember the following: What warnings, cautions and notes are necessary? Often these seem to be added almost as an after-thought.
An aspect of quality technical writing not given much attention is the manner in which the actual manuscript is presented, or written. It is not a matter of "jotting" down technical information: with a piece of information forgotten or omitted.
There is a tendency with some writers to adopt the attitude of: "the proofreader will fix it". They do not take the extra effort of getting it right, themselves, FIRST TIME. This attitude often results in the text being unclear to the proofreader and time being wasted in that the proofreader has to clarify the text with the writer. It is also not very cost-effective and as a result increases the price of the documentation, or erodes the profit margin.
The research stage is where quality technical writing begins. A writer should never rely on his mental notebook, no matter how technically skilled he may be.
While doing research and/or interviewing persons, always make notes, or better still, have a pocket cassette recorder. In gathering mounds of source material it is inevitable that something will be lost. Remember, RESEARCH IS THE FIRST STEP IN THE PROCESS OF QUALITY DOCUMENTATION, and this is the responsibility of the writer.
A quality piece of technical documentation stems from the writer, although the total quality process does not rest solely on the writer’s shoulders. Something worth remembering is that the proofreader should always only need to neaten a piece of writing, like adding comma’s, NOT RE-WRITE BLOCKS OF TEXT. The proofreader should never need to read a sentence, paragraph, etc. twice (or more) to understand its meaning. If this occurs, think of the reader of the document!
E.J. Marsden, in the book TECHNICAL WRITING & PUBLICATION TECHNIQUES gives the following three questions a writer should ask when reading over his work:
a) Is there another form of words better suited to the context?
b) Is it possible to make a clearer statement?
c) Can the text be made easier to read?And on proofreading Marsden has the following advice:
"Proofreading, to be valid, must be done by responsible and suitably qualified personnel, to a set of simple rules."
Here then are simple proposals for quality technical writing. If, through this article, technical writing improves only somewhat, something positive has been achieved.
Return to Articles.
Please don't hesitate to contact us, for further information, or give your comments. E-mail: info@cyberdoc.co.za Tel: (011) 814-7101. Your enquiry will be dealt with in less than 48 hours.This article was printed from the web site of CYBERDOC cc (www.cyberdoc.co.za).