Charles Leiserson Tips for Technical Writing

Here are some useful tips about technical writings that I learned from Charles in his advanced performance-engineering class:

• Avoid word New in the title (it will not be new 20 years from now). The same problem about novel (less serious).
• Avoid needless words in the title ("building a").
• avoid week words such "is" "to be" and "have". e.g., replace "they are unable to" with "they largely fail".
• Always embed "however" in the middle of sentence. It is not the same for "But". In that case, use short sentences (break "xxx , but" with "xxx. But," ). 
• Verb is the most important part of the sentence. After that, the subject is the second important. So, never restrict a subject to a "This". Add a noun after "This". Also, avoid "it", e.g., avoid "it is clear that".
• Related to the previous point, replace instances of "is focused on" with "focuses on" (a more powerful verb).
• Avoid semicolons as much as possible.
• It is OK to have passive verbs, however, only when it is required. 
• If you are using "while" as a connector, replace it with "whereas".
• Replace instances of "very" with "damn" and then remove "damn" (inspired by Mark Twain diary). For example, replace "very good" with "excellent".
• Be careful about hyphenating. "cloud-computing services" is different from "cloud computing-services". No need to hyphenation of "quickly growing function" because "quickly is clearly adverb (do not hyphenation adverbs ending with "ly").
• Use "Performance-Engineering" instead of "Performance Engineering" because it the subject. In this example, "Performance-engineering" and "Performance-Engineering" are both fine. In similar situations, always make "Is" capitalized because it is a verb,
• Replace "There are a number of " with "There are several" or "There are many". Then geAlso, "there are has previous problems.
• Use present tense. Avoid future tense and, even worse, "would" "could", etc. It is fine to use past tenses depending on the context.
• Make a context first in long sentences: "when attempting XX, teachers face YYY" is better than "Teachers face YY when teaching XX". 
• It is OK to Highlight a term in both abstract and body
• "IDs" vs "ID's". Acronym to be plural do not need apostrophe in modern English. Charles is OK with the old style, however. 
• "a, b, and c" is preferred to "a,b and c".
• This is about using digits vs spelling of numbers. Knuth says if the number is less than 10/12, then you spell it out; otherwise, use digits. However, it is a bad rule for technical writing. Let's do the following: If you do math on numbers, use digits, otherwise, follow the other rule. 
• Be cautious in using "we", since it can be all authors or authors plus readers. The distinction should be clear. 
• The first sentence of the paper should be about contributions rather than describing. 

Here is an example:

Performance-Engineering of CilkSan

Compressed Dictionaries for Optimizing the Shadow Memory

This paper explores new solutions for maintaining the shadow memory of CilkSan, a debugging tool that detects determinacy races in programs written in Cilk. At the heart of CilkSan lies the SP-bags algorithm, which is a provably good, efficient race-detection algorithm. The SP-bags algorithm maintains a shadow memory data structure that stores the IDs of the previous reader/writer procedures for each memory location. Unfortunately, the large size of the shadow memory is a bottleneck for detecting races for programs with high memory demand.

We tend to decrease the size of the shadow memory by applying compression techniques. We introduce the concept of Compressed Dictionary as an abstraction of a shadow memory with high spatial locality. This abstract data-type is expected to have applications beyond CilkSan. We employ different techniques such as run-length encoding, Lempel Ziv, and Burrows-Wheeler encoding to implement a compressed data structure. Using these solutions, one expects the size of the shadow memory to be considerably smaller than the memory requirement of the current serial program. As a result, we can determine races in real-world applications in which the current version of CilkSan fails due to excessive memory usage.