Henry
Corrigan-
Gibbs

Suggestions for Technical Writing

July 2025

Here are a few simple suggestions that I often make when editing papers. Some of these tips I learned from Dan Boneh.

If you use LaTeX (and you should!), I recommend reading Eddie Kohler's LaTeX usage notes. Eddie's notes inspired me to put this page together and also inspired its style.

Introduce as few variables as possible.

The reader has to keep track of every variable you introduce. The more variables you use, the harder the reader has to work to understand what you are saying.

• First, \(C\) sends \(\rho\) to \( S \). Then, \( S \) forwards \(\rho\) to \(O\).

• First, the client sends its request to the server. Then, the server forwards this request to the origin.

Use as few abbreviations as possible.

Like variables, abbreviations make a paper more difficult to read. Whenever you can, just write out the full phrase. It takes a little more space, but often the major gain in clarity is worth the minor cost in word length. Avoid introducing abbreviations in your paper's abstract.

• We improve the SOTA by…

• We improve the state of the art by…

Use suggestive variable names.

To help your reader remember which variable corresponds to what, pick variable names that relate to their meaning/use.

• Encrypt the message \( a \) with key \( b \).

• Encrypt the message \( m \) with key \( k \).

Add context when referring to variables.

Every time you refer to a variable in prose, add some context around it to help the reader remember what the variable refers to.

• Encrypt \( m \) with \( k \).

• Encrypt the message \( m \) with key \( k \).

Make references specific.

When referring to another part of your paper, or to another paper, be as specific as you can. This saves the reader time when they want to track down a reference.

• In the figure above, …
• As Smith [34] proves…

• In Figure 3, …
• As Smith [34, Lemma 7] proves…

Typeset your system's name in title case (not in upper-case letters).

There is no need to YELL your system name at the reader.

• This paper describes RADICALDB, the first system…

• This paper describes RadicalDB, the first system…

Avoid passive voice.

Passive voice makes it difficult (and sometimes impossible) for the reader to figure out who is doing what.

• The digital signature is verified.
• The server is trusted for availability.

• The client verifies the digital signature.
• A malicious server may deny service to clients.

Make performance claims quantitative.

It is tempting to use fuzzy phrases like "much faster than" and "low overhead" to describe system performance. It is not clear what these phrases mean. If you replace these phrases with specific numbers, there will be no ambiguity.

• Adding ABC encryption imposes minimal bandwidth overhead.

• Adding ABC encryption increases the length of each packet by 10 bytes at most.

Make the caption of each figure the "thesis statement" of the figure.

Each figure in your paper should have a point—something that the figure is trying to show. If you put this point in the caption of your figure, the reader will immediately see what you are trying to show.

• Figure 1: A plot showing the query-processing time of RadicalDB as the database size varies.

• Figure 1: RadicalDB's query-processing time scales logarithmically with the database size.