Technical Writing in a Nutshell
By Jay Jacobus
When writing for a technical audience, some writers fail to get their point across even though they are proficient in their field. Other writers write clear short articles that reap them justified praise. It may seem odd that the some of the most intelligent, creative minds in a particular discipline are not well recognized. It may seem odd, but it really is quite understandable. These gifted people don't have trouble thinking up many good ideas. Rather they have trouble getting their ideas across.
This observation may apply to many mathematicians, programmers, scientists, engineers and technical writers. However, I am mostly concerned with professionals who write Manuals because I sometimes read their manuals and puzzle over what they are trying to say. This can be embarrassing for them and uncomfortable for me when I ask a writer to explain his unclear text. The typical technical writer's reaction is disbelief that I am ignorant concerning their discipline. This reaction is annoying. I am perfectly capable of reading science magazines and technical papers that are well written, but when they are poorly written, I blame the writer for his paper's ambiguity, complexity and incomprehensibility.
If the subject is too tough for me, I will say to myself, 'This paper seems to be well written but the topic is over my head.' I will then put the paper down and never think about it again. I certainly won't make a fool of myself by asking the author to use simple English that I can understand. I will only ask the author to explain if it is essential for me to understand and I honestly believe that I can understand if given a clear enough explanation.
Some technical writers will read this article and say, 'This is not a good example for us to follow. It is too informal. The style is not suitable for technical writing.'
Some technical writers use the passive voice which sounds formal. The passive voice uses 'to be' as the most utilized verb. The active voice uses descriptive verbs. In the prior six sentences, three are in the passive voice.
They are still understandable. So, the passive voice can be clearly utilized, but it has some problems.
The first problem is the lack of meaning in the verb 'is, were and are'. Take the simple statement, 'The book is black.' The words 'book' and 'black' give meaning to the sentence. The word 'is' does not add meaning. Instead, it is needed to make the two important words into a sentence. If a teacher says, 'The book is black', the class may not know what to do. Perhaps, they should take out their black books. Perhaps, they look for the black book. Perhaps, the teacher is addressing the whole class or she may be talking to one individual. The sentence, 'The book is black', is in the same form as an insinuation. Could the teacher be insinuating something? If the context of the statement does not clarify the statement, a student may think, 'Why is she saying that? Is it something we did?'
The passive form of the statement can make the statement unclear and confusing to the reader.
If the teacher said, 'The black book should be brought to me by James.' then she is being clearer, but the sentence sounds unnatural. So, the passive voice can be used clearly but at times will sound unnatural. Most readers can adjust to the passive voice and understand unnatural sounding sentences but it takes time to get used to this style of writing and the reader's comprehension may slow down. For the technical writer, this is a bad thing. The technical writer may be challenging the reader with difficult ideas, but he should not use wording that increases the reader's challenge. Rather he should create a paper that can be read from start to finish without stopping to puzzle over meaning.
It's better to have a mix of passive and active voiced sentences that read smoothly.
The sentence, 'Bring me the black book, James.' is clear and natural.
The reader who wants to be clear can start by critiquing the wording of other technical writers.
Which writers are clear and natural and which ones are imprecise and unnatural? By paying attention to each author's use of the passive and active voice, the reader can start seeing what works well and what doesn't.
One thing is for sure: knowing about the weaknesses of the passive voice will help all technical writers improve their understandability.
To be certain that I have clearly identified passive sentences, let me give some additional rules:
Passive voiced sentences often have a subject that is inanimate, like 'the book was brought by James.' Active voice sentences have a subject that is alive such as people. For example, 'James brought the book', is active.
Sometimes a writer using the passive voice will exclude the active person from the sentence entirely. This is the case in the following sentence; 'All documents must be filed in their appropriate drawers.' The sentence does not specify who does the filing. Is it the file clerk? Is it the document user? The office assistant?
Leaving out the active person is a common error of people who use the passive voice. If a technical writer must use the passive voice, he should reread his paper and add 'by the clerk (or whomever)' to all passive sentences that are unclear or he should make the sentences active.
'Give the file clerk the documents that you have finished using. She will file them in their appropriate places.' Not only are these sentences active, but they are two sentences instead of one. Two simple statements may flow better than one long sentence. Consider the alternative passive statement: 'All documents are filed in their appropriate drawers by the file clerk who gets the documents from people who are done using them.'
Some technical writers lean toward long sentences which are cumbersome and unnatural.
Consider the following statement:
'It is the essence of scientific investigation to be fastidious and conscientious about extracting deductions when approaching an innovative conceptual factor from the hypothetical assumption given a random dispersion of non-static variables that arise out of the re-compilation sample and thus warn the director of obtuse investigative downturns.'
The above statement is unclear, unnatural sounding, long and complex. Besides using the passive voice, the technical writer should use common words1, less prepositional phrases2 and eliminate negative words3.
1 - In the contrived statement above, the writer could simplify word usage by changing the word essential to basic, the word fastidious to demanding, the word extracting to obtaining, etc. You might also know that the least intelligent man often uses the most arcane wording because arcane wording makes him think that he is giving an impression of being intellectual. This is the wrong attitude. The technical writer should try to identify with his audience so that he can pick the most appropriate wording.
2 - To eliminate prepositional phrases, eliminate unnecessary words and phrase and change prepositional phrases into simple adjectives, write phrases like 'his bike' instead of 'the bike that he owned.'
3 - Under the heading of confusion comes negating a word. Non-static might mean variable, so say variable instead. Then notice that the phrase 'non-static variables' becomes 'variable variables' which can be condensed down to simply variables.
Another tip is to eliminate as many references as you can. References that are crucial to the point of a section make the reader stop and search. It is kinder to insert the reference directly into your text if the reference is not too long. Even graphs and exhibits can be inserted twice, once where you explain how the exhibit is derived and then later when you reference the exhibit as an example. If the reference is not crucial to understanding, it should be referenced at the end of the paper rather than disturbing the reader's concentration.
You can also disturb the reader's concentration by using many acronyms and defining them only at the beginning of the paper. If you define the acronym, QMS, as a quality management system, do not think that the reader will remember the acronym throughout your paper. Unless it is a widely known acronym such as IBM, you should use quality management system instead of QMS throughout a short paper. That way the reader doesn't need to memorize all your acronyms to be able to read your paper. If the acronym is in a book and is a key acronym, you should use your judgment regarding how long the reader will take to get comfortable with the meaning of the letters. When you are sure that you have overdone the definition to that point that even the person with a poor memory will remember it, use the acronym alone. Even so, writing, 'QMS (quality management system)' every so often is a good idea.
The suggestions in this article are meant to help the technical writer become more readable. Taking some of my advice will help some writers improve their clarity. Hopefully, every occasional writer will come away with some helpful hints.
For people, who need more help than this short article provides, a skilful tutor, technical writer or local professor can improve style, rephrase complicated text and clarify wording.
One of my pet peeves is with companies that encourage their technical professionals to write papers but leave them without the proper assistance to write well. Often, the untrained writer's only example is an overconfident manager who thinks that he can write well when he can't. Managers should either get the proper training or turn the writing advice over to a writing teacher. This simple rule would break the chain of passing on poor writing skills from manager to subordinate.
