Technical Writing

This is a compilation of my pet peeves and of some common mistakes I often come across in technical writing. It is not authoritative, a little cranky at times, and meant primarily for my students (each topic was originally an email that I sent to my students, semi-periodically). Most examples come from writing on topics related to wireless networks.

Allow, Permit, Enable

This is one appears all the time and is dedicated to Danny, who shares my pet peeve.

Allow, permit, and enable are verbs that really require a direct object, which some authors insist on leaving out.

Example: “The algorithm allows to detect incumbent signals below the noise floor.” [Correction: “allows the radio,” “allows us,” etc.]

Note: This type of mistake is sometimes referred to as “Brussels English,” as it seems prevalent in European research writing (project deliverables, etc.). There is even an official document that compiles common misused words in EU publications: http://ec.europa.eu/translation/english/guidelines/documents/misused_english_terminology_eu_publications_en.pdf

Literally

A few years ago, Sarah Palin’s spokesperson was mocked for saying that “the world is literally her [Ms. Palin’s] oyster,” a statement that is hard to make sense of if the word “literally” is, well, taken literally.

It turns out, however, that the spokesperson may have been right after all. There is current debate that the word “literally” should be defined as:

1. In a literal manner or sense; exactly;
2. Used to acknowledge that something is not literally true but is used for emphasis or to express strong feeling.

(Source:http://www.slate.com/blogs/browbeat/2013/03/06/literally_definition_has_changed_over_the_years_dictionaries_recognize_this.html)

In other words, literally currently can mean: (a) literally; or (b) not literally.

For recurring jokes on “literally” versus “figuratively,” I recommend Archer (animated series available on Netflix, most definitely not for children).

Whom or who

This one is easy: “who” and “whoever” are used as a subject, and “whom” and “whomever” as an object. Examples:

“Whoever reads these obsessive writing tips is guaranteed to improve his or her [“their” is also acceptable here, and some would prefer it] writing skills.”

“To whom it may concern…”, “For Whom the Bell Tolls”

“Whoever operates in licensed spectrum (…)”

It gets a little tricky when you have entire clauses serving as an object:

“The wireless nodes may disagree as to who should gain access to the band.” (“Who” is the subject of the clause “who should gain access to the band.”)

The greengrocer’s apostrophe

The greengrocer’s apostrophe is a superfluous apostrophe incorrectly used where the word simply calls for a plural.

This is a major problem afflicting restaurant menus, but thankfully it doesn’t show up much in technical writing. But I often see errors in technical papers resulting from possessive forms of a noun, in particular when dealing with plural nouns. For example:

“The node’s radio interfaces are tuned to the same channel.”
versus
“The nodes’ radio interfaces are tuned to the same channel.”

The first case implies a single node with multiple interfaces. The second case implies multiple nodes (there is some ambiguity with regards to how many interfaces each node has, but I would assume a single interface per node unless there is clear contextual evidence to the contrary). Both are correct, depending on what you mean (one node or multiple). “The nodes’s radio interfaces,” however, is nonsense.

Possessives can get a little awkward with proper nouns ending in “s”. Is it “Charles’s algorithm” or “Charles’ algorithm”? Some styles manuals recommend the first, but I believe both would be acceptable, unless it starts to sound strange (e.g., “Moses’s” or “Jesus’s”).

Misplaced modifiers

This week’s topic is inspired by the subject of an email I received from the IEEE today: ‘Video Previews by Chairs & Organizers of Exciting Developments at OFC/NFOEC.’ I am almost sure what they meant is: ‘Video Previews of Exciting Developments at OFC/NFOEC, by Chairs and Organizers.’

Misplaced modifiers are common and they completely alter the meaning of the sentence.

Example: The student failed almost all his classes. (versus) The student almost failed all his classes.

The fix is usually simple; the hard part is recognizing that there is a problem.

Effect and affect

This one is by request. It does show up a lot in technical writing and it is easy to make a mistake.

Affect is a verb (in 99.999999% of the ways that you’d ever want to use the word in a paper or thesis).

Example: ‘Mobility affects the stability of established routes in the network.’

Effect is a noun (in 99.5% of the ways that you’d ever want to use the word in a paper or thesis).

Example: ‘Work in [8] analyzed the effects of DSA in a single-tiered LTE+ network (…)’

Suggested mnemonic: nevah (‘never’ pronounced by Sir John Gielgud playing a British aristocrat) – noun/effect, verb/affect.

There are cases where affect is a noun (e.g., ‘The patient displays a happy affect.’) or where effect is a verb (e.g. ‘The new provost wants to effect change.’). But they are not likely to appear in your technical writing.

Can not or cannot

Although both are acceptable, “cannot” is generally preferred.

The OED simply claims “cannot” is the modern way of writing “can not,” and proceeds to give an example from 1400: “And þou þat he deed fore cannot sorus be.”

Some other sources I found split some hairs, but I think using “cannot” is safe enough. An exception is when the “not” really belongs in an expression, like “not only”, e.g., “Our simulation can not only verify the claim in the theorem, but it also provides some additional insight into (…).”

PS: Of course, there is also “can’t” – but contractions are for another time.

Whether or not

I wasn’t sure whether or not the use of “whether or not” is grammatically correct. As it turns out, it seems it is, although most advice I can find discourages it (see exception below).

The bottom line is that in most cases the “or not” is superfluous, so you’re just wasting keystrokes and the reader’s time. In extreme cases, it may even extend your paragraph into an extra line, which may extend your paper into a new page, which may result in extra page charges. And, voila’, your unnecessary “or not” has cost hundreds of dollars.

Consider:

A: It is up to the destination to determine whether or not the packet was received without errors. (OK)
B: It is up to the destination to determine whether the packet was received without errors. (Better)

Exception: “The destination issues an ACK whether or not an error was detected in the packet.” In this case, the “or not” is needed. The sentence means, and is probably more clearly expressed as, “The destination issues an ACK regardless of whether an error was detected in the packet.”

PS: The issue of “if” versus “whether” is more complex. The short, somewhat over-simplified guideline is to use “if” to express condition and “whether” to express alternatives.

Unnecessary quotation marks

Quotation marks should be used for, as the name implies, quotations.

Example: Deaton [3] shows that, “by the simple addition of a Spectrum Accountability Server to the LTE-Advanced architecture, it is possible to incorporate dynamic spectrum access into 4G networks.”

They can also be used when referring to titles of journal/conference papers.

Example: In his paper “Cognitive Networks” Thomas [15] defines (…)

Quotation marks should not be used to indicate emphasis. Random unnecessary quotation marks can be often found in signs, posters, menus, etc., sometimes to bizarre effect.

Countable and uncountable

Some words are used for countable nouns and some for uncountable (and some for both). Here are some examples that I tend to see often when editing papers:

1) few (countable) versus little (uncountable): ‘a few nodes,’ but ‘little performance improvement.’

2) number (countable) versus amount (uncountable): ‘the number of packets’ but ‘the amount of overhead.’

3) many (countable) versus much (uncountable): ‘many messages’ but ‘much degradation in QoS.’

Also note, in reference to a previous discussion of plural/singular, that countable nouns pluralize but uncountable nouns generally do not. Hence, ‘the performance of the nodes’ but ‘several performances of Cirque du Soeil.’

Comma separating the subject from the predicate

The subject of this week’s email is one that I see a lot in my students’ writing (not naming names…).

When the subject is long, there is the impulse to break things off with a comma, to give the reader some time to breathe, or get a beer, or something, before continuing the sentence. This is very considerate of the writer. It is also, in most cases, wrong.

The subject generally is not separated from the predicate by a comma. An example:

Forwarding packets and participating in the exchange of route establishment and maintenance messages, are two of the functions that nodes in an ad hoc network must perform. (Incorrect. Please remove the comma.)

One exception is the case of a parenthetical statement coming between the subject and the predicate: in this case the parenthetical statement is lodged in the warm embrace of two commas. Example:

Cognitive radios, first introduced by Mitola [1], are often associated with dynamic spectrum access. (Well done on the comma! Not so much on the nowadays unnecessary and somewhat lazy reference.)

The passive voice

‘Never use the passive where you can use the active.’ (George Orwell, ‘Politics and the English Language,’ Horizon, 1946)

The topic is complicated and I won’t even try to get very general. I don’t fully understand all of the implications of the use of the passive voice, and there is a recent article in the Chronicle of Higher Education where the author rants in favor of the passive voice (in certain circumstances). I think he has a point, and maybe Orwell’s advice is too broad.

But, specifically: avoid the passive voice when describing your own work in a research paper/thesis/dissertation.

Technical papers are all about making a case for your contribution. It is, therefore, self-defeating to hide the subject of a sentence when the subject is you.

Example: ‘Experiments were conducted to show that low-cost sensing devices provide sufficient sensitivity for clear channel assessment.’

While it may be clear from context that said experiments were conducted by you, it is preferable to leave no possible ambiguity: ‘We conducted experiments (…)’.

Comma + quotation marks, and period + quotation marks

After living in Ireland, I am no longer obsessive about this one, but here is the rule…

When we write in American English, a comma or a period get “absorbed” by the quotation mark, regardless of whether the comma/period is actually part of what is being quoted. The rule is somewhat nonsensical but easy to follow.

Example 1: The IEEE 802.11 WLAN technology is sometimes referred to as “WiFi.”
Example 2: At CTVR we seek to design networks that are “submissive,” which can easily adapt to different economic and regulatory models of operation.

When writing in the Queen’s English, the rule is different. The comma or period get absorbed by the quotation marks only if they form part of what is being quoted. In the examples above, the comma and the period would follow the quotation marks.

PS: There is actually an exception to the rule in American English, having to do with a single letter or a number in quotations, if you must be really obsessive about these things…

Novel (adj.)

The adjective ‘novel’ is a perfectly fine word. It has, however, been woefully abused by our research community. I found, in IEEE Xplore alone, 187,473 papers when I searched for the word ‘novel.’

Let us suppose, for a moment, that ‘novel’ is simply a synonym for ‘new.’ Then it seems unnecessary to point out that we are proposing a ‘Novel Topology Control Mechanism for Ad Hoc Networks,’ as it is safe to assume the reader expects a research paper to propose something new. In fact, it would be quite novel to entitle a paper ‘An Old, Rehashed Topology Control Mechanism for Ad Hoc Networks.’

But, arguably, ‘novel’ means more than ‘new.’ According to Webster, it means ‘new and not resembling something formerly known or used,’ or ‘original or striking especially in conception or style.’

So, in my opinion, the adjective ‘novel’ must be earned. (The seminal paper by Finn applying trampolining techniques to dynamic spectrum access is an example of truly novel work.) But, even when it is earned, I would still not use the word since it has become, in our community, such a cliche’.

Plural and singular

Here are a few singular/plural nouns that may raise some doubt. I am sticking to words that appear frequently in the context of our work.

1. The word ‘data’ is technically the plural of datum, but its usage as a singular noun is also generally accepted. So, ‘the data show that…’ and ‘the data shows that…’ are both acceptable.

2. The word ‘criteria’ is plural. Example: ‘The criteria used to assess the performance of the algorithm include response time and computational complexity.’ The singular form is ‘criterion.’ Example: ‘The main criterion we use to quantify the performance of this protocol is aggregate network throughput.’

3. Performance, in the context in which we tend to use the word, is not generally pluralized. Example: ‘The performance of the nodes is assessed using the following criteria.’ (With another meaning, it would be pluralized, e.g., ‘I have watched several performances of Cirque du Soleil.’)

Hyphens

The topic of hyphens could probably generate a half-dozen of these emails (and probably will…). But, for now, I’ll stick to some cases that are pretty common in technical writing.

When a noun-adjective combination modifies another noun and appears before it (essentially serving as an adjective), it is hyphenated.

Example 1: User-deployed femtocells have the potential to considerably increase the overall capacity of 4G networks.
Example 2: Provider- and user-deployed femtocells have the potential to (…).

This, by the way, also happens with certain adverb-adjective combinations (but, oddly enough, not when the adverb ends in -ly).

Example 3: The well-known work by Finn [1] has given rise to the new research field of trampolining-inspired wireless resource allocation.
Example 4: The widely referenced work by Finn [1] has (…)

Respectively

This week’s topic is very simple, but I keep seeing ‘respectively’ used unnecessarily.

‘Respectively’ means ‘in the specific order in which the items are listed.’

Good:  N and M denote the number of radios and the number of channels, respectively.

Bad: N denotes the number of radios and M the number of channels, respectively.

Than

To decide whether to use subjective pronouns (I, he, she, etc.) or objective pronouns (me, him, her, etc.) after ‘than,’ you should think about what the sentence would look like if you were to repeat the verb after the pronoun.

Example:
‘This technique is older than I.’ (‘This technique is older than I am.’)

For an example of how the choice of object/subject pronoun may change the meaning of the sentence, refer to the song ‘Hard to Handle,’ by the Black Crows (example courtesy of Prof. MacKenzie):

Actions speak louder than words
And I’m a man of great experience
I know you’ve got another man
But I can love you better than him.

As written, this must be interpreted as ‘I can love you better than I can love him,’ although it is likely the intended meaning was ‘I can love you better than he [can love you].’

To capitalize or not after a colon

There are some differences in British/Irish versus American English on this point, and to some extent it is a matter of style rather than a rule. To make things simple, I think the following would be pretty widely accepted.

If the word after the colon starts an independent clause, capitalize it. Otherwise, don’t. (Obviously, if the word is a proper noun, capitalize it regardless.)

Examples:

1. There are three types of people in the world: those who can count and those who can’t.

2. The results in Figure 3  lead to the following conclusions: The MARATHON topology control outpaces other traffic-aware mechanisms in terms of energy consumption. And MARATHON provides the network with a running start on a stable topology, followed by a cool-down period when few link changes occur.

i.e. and e.g.

This one is by request. The abbreviation e.g., which Paolo can probably tell you comes from the Latin exempli gratia (I looked it up, I don’t really know Latin), means ‘for example.’

The abbreviation i.e., from the Latin id est, essentially means ‘that is.’

Examples:

1. Trampolining jumps (e.g., pike, straddle, seat drop) require similar allocation of resources as network scheduling algorithms such as fair queuing and weighted round robin, as persuasively argued by Finn [3].

2. Under favorable conditions, i.e., with high SNR and negligible fading, we can assume all nodes in the region of interest to be within transmit range of one another.

Each other / one another

I decided to double check this point and found out that the rule is more controversial (or just fuzzier) than I thought.

The general rule (or so I thought until minutes ago) is that ‘each other’ is used when there are two parties involved and ‘one another’ when there are more than two.

Examples: ‘transmitter and receiver talked to each other…’; ‘N network nodes communicated with one another…’

It turns out that this is not a firm rule, but more of a convention. Anyway, it will make me happier if you use it as above, but if you don’t I will no longer obsess about it.

The subjunctive

A pre-takeoff flight announcement often goes like this: ‘It is important that your luggage is safely stowed in the overhead bins.’ I always want to say: ‘This may well be true and it is even grammatically correct, but it is not at all what you mean. You mean that it is important that the luggage be safely stowed.’ (If I’m travelling with a friend, I often do say it…)

The indicative mood is reserved for actions that happen in the present, happened in the past, or will happen in the future. The subjunctive mood expresses possibility, necessity, a hypothetical, etc., and it generally deals with actions that are not real yet. (If you simply want to say that all luggage is currently safely stowed, then the indicative is fine. But if you want to impress on passengers that, for their safety, they should stow any luggage that may be currently lying around and might hit them in the face during takeoff, then you really need the subjunctive.)

Other examples of the use of the subjunctive:
‘It is necessary that each node forward all packets to its immediate neighbor.’
‘I asked that Danny write a paper discussing the commonalities between trampolining and dynamic spectrum access.’

There are ways to avoid the use of the subjunctive in the examples above, if you really are bothered by how the subjunctive sounds in those cases:
‘It is necessary for each node to forward…’ or ‘Each node should forward…’
‘I asked Danny to write…’

a/an

You may have learned that you should use the indefinite article ‘a’ before words starting with a consonant and the indefinite article ‘an’ before words starting with a vowel. If you did, you were taught wrong.

[I think this is the way I was taught in Brazil way back when. But then again, I was also taught that the English word for the little green citric fruit used in caipirinhas was ‘lemon.’ This is a misconception that persists in Brazil, where Coca Cola Lemon is sold, a prominent drawing of a lime on the can. But I digress. Back to indefinite articles…]

The real rule is that ‘an’ should be used before words that start with a vowel sound. So, it’s ‘an umbrella’ but ‘a unicorn.’

The rule also applies before an acronym: ‘an RTS frame,’ ‘an LTE network,’ etc.

When should I use the word ‘very’ in technical writing?

Never.

OK, this is a bit too radical, but 9 times out of 10 I find that the use of ‘very’ comes across as a bit desperate (e.g., ‘the results are very promising’).

Mark Twain on the topic:
‘Substitute “damn” every time you want to use the word “very.”  Your editor will remove the word and your writing will be as it should.’

Split infinitives

This one is by request. Split infinitives have never bothered me, so I had to look the topic up to find out whether they’re really OK.

A split infinitive occurs when you place an adverb in the middle of the infinitive. Perhaps the most commonly cited example comes from Star Trek: ‘to boldly go where no man has gone before.’

It turns out that split infinitives are generally fine, so feel free to merrily split your infinitives.

The only minor caveat is that the placement of the adverb may affect the meaning of the sentence; e.g., ‘to live simply’ means something different than ‘to simply live.’

On the other hand…

This is a bit of a cliche’, so it may be better to think about alternatives (‘by contrast,’ ‘on the contrary,’ ‘conversely,’ etc.). But if you feel like using it…

The expression is meant to be used when you are describing opposing ideas.

Examples:
‘If Men of Eminence are exposed to Censure on the one hand, they are as much liable to Flattery on the other.’ (A quote from 1711.)

‘On the one hand, I think it is a good idea to send my students weekly writing tips, in the hope that we will all end up improving our writing skills. On the other hand, I fear my students will add my email address to their spam filter.’ (A quote from 2011.)

Example of a questionable (or worse) use of the expression:

‘Finn et al. [3] show that the requirements of trampolining are exactly the same as those of dynamic spectrum access. On the other hand, in [12] Irwin proposes a new channel assignment scheme, called MARATHON.’ (There is no direct opposition between the two ideas, even though they may be completely different.)

et al.

An abbreviation from the Latin ‘et allia,’ meaning ‘and others,’ the main use of ‘et al.’ in the context of papers we write is when citing papers whose number of authors exceeds some threshold.

Example: [3] D. Finn et al., ‘Cooperative Spectrum Sensing and Trampolining: A Comparative Analysis,’ Journal of Improbable Multi-disciplinary Research, vol. 2, no. 4, pp. 1384-1397, 2011.

Some comments:

1. Note there is no period after ‘et’ – this is because ‘et’ is not an abbreviation, it just means ‘and’ in Latin.

2. The threshold for the number of authors that will justify the use of ‘et al.’ is a subjective matter. You should never use it when there are only two authors. The IEEE Computer Society recommends its use when there are more than three authors. I have seen guidelines that suggest its use when there are five or more. It is up to you: just remember that you are denying those authors referred to as ‘others’ their moment of glory.

The serial comma

The serial comma is the comma that precedes the last element of a list linked by ‘and,” or,’ or other conjunctions.

Example: ‘DSA is supported through the use of a cognitive base station, spectrum server, and cognitive user equipment.’ (The last comma is a serial comma.)

The use of the serial comma is controversial in certain circles, but I think its advantages outweigh its disadvantages and I almost always use it.

The traditional example of what can go wrong if you don’t use the serial comma is the following (apocryphal) dedication: ‘I dedicate this thesis to my parents, Ayn Rand and God.’