UP | HOME

Some notes on technical writing

Table of Contents

A note after reading this article: http://matt.might.net/articles/shell-scripts-for-passive-voice-weasel-words-duplicates/

In his article, Mr. Might claimed that there are 3 common problems of technical writings:

  1. weasel words
  2. abuse of passive voice
  3. lexical illusions

1 Weasel Words

Are the phrases or words that sound good but convey no information.

There are 3 kinds of weasel words: (1) salt and pepper words, (2) beholder words and (3) lazy words.

1.1 Salt and pepper words

Some of them are: various, a number of, fairly, quite,…

Some example:

Bad: It is quite difficult to find untained samples. Better: It is difficult to find untained samples.

1.2 Beholder words

Words or phrases that express a judgment of the reader, but it's actually the reaction of the writer: interestingly (you may find it interesting, but how do you sure the reader is too?), surprisingly, remarkably, clearly,…

Example:

Bad: False positives were surprisingly low. Better: To our surprise, false positives were low. Good: To our surprise, false positives were low (3%).

1.3 Lazy words

Words give the impression that the work is unfirm, unfinished or does not have quantitative information. They're very, extremely, serveral, exceedingly, many, most, few, vast,…

Bad: There is very close match between the two semantics. Better: There is a close match between the two semantics.

1.4 Adverbs

Insert adverbs frequently will weaken the sentence instead of strengthen it.

Bad: We offer a completely different formulation of CFA. Better: We offer a different formulation of CFA.

2 Passive voice

This is interesting, I've seen Grammarly trying to remove my passive voices so many times. Not always, but we should reduce the use of them.

The passive voice is bad when it hides relevant or explanatory information.

Bad: Termination is guaranteed on any input. Better: Termination is guaranteed on any input by a finite state-space. OK: A finite state-space guarantees termination on any input.

When you caught yourself using a passive voice, ask the two questions:

  1. Is the agent relevant yet unclear?
  2. Does the text read better with the sentence in the active?

If both answers are "yes", change to the active. If only one "yes", specify the agent.

3 Lexical illusions

Lexical illusions is when the brain automatically skip the duplicates words, it is really hard to detect, better use with a checking script.

Example of lexical illusions:

Many readers are not aware that the the brain will automatically ignore a second instance of the word "the" when it starts a new line.

Date: 2019-01-24 Thu 00:00

Author: Huy Tran

Created: 2019-04-22 Mon 14:41