Technical Writing Part 1
Some Principles of Effective Technical writing
NB: This writeup is based on notes I took while completing the Stanford University Writing in Sciences course on Coursera
“As a technical communicator, I am an enabler of information.”
― Suyog Ketkar
What makes a good technical writer?:
- Ability to communicate an idea clearly and effectively.
- Having something to say and being passionate about the topic.
- Presenting the ideas clearly and logically.
- A few simple, learnable rules of style (We will focus on these in this post)
Questions to ask yourself:
- Is the sentence or paragraph easy to understand?
- Is it boring or interesting/enjoyable to read?
- Is the sentence readable?
- Is the sentence/paragraph written to inform your audience or obscure them?
Below are things to consider if you want to become a good technical writer.
1) Cut Clutter from Your Writing:
Good writing involves cutting a lot of clutter. The ability to depart with words you have written is a skill worthy of developing. It’s hard to depart with words we have invested so much effort to put together, however, be vigilant and ruthless when cutting unnecessary words.
“The secret of good writing is to strip every sentence to its cleanest components. Every words that serves no function, every long word that could be a short word, every adverb that carries the same meaning that’s already in the verb, every passive construction that leaves the reader unsure of who is doing what — these are the thousand and one adulterants that weaken the strength of a sentence. And they usually occur in proportion to education and rank,”
― William Zinsser,
Some Common Clutter
- Remove dead weight words and phrases: (Provide Citations instead of using them)
- As it is well known
- As it has been shown
- It can be regarded that
- It should be emphasized that
2. Remove empty words and phrases
- Basic tenets of
3. Take note of long words or phrases that could be short
- Muscular and cardiovascular performance == fitness
- A majority of ==most
- a number of == many
- of the same opinion==agree
- less frequently occurring ==rare
- give rise to == cause
- due to the fact that == because
4. Remove unnecessary Jargons and Acronyms
- Gliomagenesis == the formation of gliomas
5. Eliminate Repetitive words in sentences
- successful solutions ( Is there an unsuccessful solution?)
- new innovations 😕
6. Eliminate Adverbs
- very, really, quite, basically, generally, etc
7. Eliminate Negatives
- Not honest== dishonest
- Not harmful == safe
- Not important == unimportant
- Does not have == lacks
- Did not remember == forgot
- Did not pay attention to == ignored
- Did not succeed == failed
8. Eliminate There are and There is
- There are many ways in which we can arrange pulleys == We can arrange the pulleys in many ways
- There was a long line of bacteria on the plate == Bacteria lined the plate
The elegance of good writing comes from our ability to go back to work we have written, re-read it and take out the unnecessary words. The first draft should not be our final work.
I have only made this letter rather long because i have not had time to make it shorter.
Blaise Pascal- Lettres provinciales, 16, Dec. 14,1656
2. Use the Active Voice:
The active voice follows the format, subject, verb, object i.e she throws the ball, Martha will drive the car.
Passive Voice: My first visit to Boston will always be remembered by me.
Active Voice: I will always remember my first visit to Boston
Passive Voice: Cigarette ads were designed to appeal especially to children
Active Voice: We design cigarette ads to appeal especially to children.
Passive: The activation of Ca++ channels is induced by the depletion of endoplasmic reticulum Ca++ channels.
Active Voice: Depleting Ca++ from the endoplasmic reticulum activates Ca++ channels.
Active voice makes the sentence more direct. It emphasizes the following;
- Author Responsibility
- Improves readability
- Reduces ambiguity
“After all, human agents are responsible for designing experiments, and they are present in the laboratory; writing awkward phrases to aviod admitting their responsibility and theeir presence is an odd way of being objective.”
Jane J Robinson, Science 7 June 1957: 1160
3. Write with Verbs
Verbs make sentences go!
Compare the two sentences;
Sentence 1: The WHO reports that approximately two-thirds of the world’s diabetics are found in developing countries, and estimates that the number of diabetics in these countries will double in the next 25 years.
Sentence 2: The WHO estimates that two-thirds of the world’s diabetics are found in developing countries, and projects that the number of diabetics in these countries will double in the next 25years.
Use to be verbs purposefully and sparingly. To be verbs include Is, are, was were, be, been, am
Writing effectively is a complex yet simple task. Focus on communicating effectively with your readers.