On writing technical documents

A large part of academic work involves writing papers, reports and other technical documents. Writing well is therefore a necessary and valuable skill that one needs to develop. The only way you can develop this skill is by reading and writing a lot, and getting feedback on your writing.

It helps to copy (just the style) of good writers. Read good papers, articles, and books, and try to observe what makes this a good piece of writing. Likewise, when you read a badly written article/book, try to think about what makes it bad. Is it the structure, or the technical content, or the sentences used?

Here are some points to keep in mind when writing any technical document:

• Before you start writing anything down, you should have a general high-level idea of the flow of the document. How would you structure the various points/results/content? What should come first and what should come later? This will of course change later once you write things down, but always start with a vision. I sometimes write brief bullet points separately that helps decide the initial flow of the document. This structure is not set in stone: after writing things down, I may feel like the entire order must change. But always start with a plan. This helps you get some momentum when writing.
• Writing papers is like writing code. Only a small fraction of the time is spent in writing. The majority of the time should go to checking for and correcting mistakes, polishing sentences, cutting down unnecessary content, and improving the flow of the document. Make sure that you check, re-check, and check once again for mistakes before sending the document.
• Write conciously, and avoid making mistakes. Some typos can inevitably creep in, but you should keep this to a minimum. Writing well (or badly) creates a strong positive (or negative, if bad) impression of you in the minds of the readers.
• Never plagiarise: make sure that you write each sentence in your own words. Draw your own figures. If there is a strong reason to reproduce a sentence/lemma/theorem from another paper, make sure that it is attributed correctly.
• Always keep the reader in mind when writing. More often than not, the reader will not be an expert in the specific problem that you are working on, and your paper must be able to convince him/her that your work is good (and correct). It sometimes helps to keep one person (maybe a colleague or a friend who works in a similar area) in mind to fix your audience. Will that person be able to fully understand the main arguments, with no additional help, just by reading the paper?
• Make sure that you use consistent notation, and that there are no typos. If it helps, write down (either handwritten on paper, or in your document itself) a table of notation and stick to it. There is nothing more confusing that notation that is incorrectly used or not defined anywhere.
• When writing down proofs, every step should be well-justified. Give appropriate references to the lemmas/theorems/equations you are using to go from one step to the next. Once again, follow consistent notation for references. Typically, for equations, use something like "from Equation (\ref{eq_label}), we have" or even "from (\ref{eq_label}), we have". Similarly, "From Lemma~\ref{lemma_label}" or "From Theorem~\ref{theorem_label}", and so on.
• It also helps to follow some system in labeling equations, theorems, and lemmas. Think of these like variables you would use in a program. When you start writing papers, there is a tendency to use labels like \label{fig1}, \label{thm1} and so on, but these will get very confusing when you have long documents. Instead, use more descriptive labels like \label{eq:subexp_tail_bound}, \label{thm:mse_main} and so on that will help you remember what each label corresponds to. I generally use \label{eq:label} to denote equations, \label{thm:label} for theorems, \label{lemma:label} for lemmas, \label{corr:label} for corollaries, and so on.

There are some minor points to keep in mind:

• Do not overuse \(\implies\).
• When you have a sequence of mathematical steps/simplifications, use the align environment.

Recall that $\bE[X_i]=\mu$ for all $1\leq i\leq n$. Then,
  \begin{align}
    \mathbb{E}[\sum_{i=1}^nX_i] &= \sum_{i=1}^n\mathbb{E}X_i &\label{eq:lin_exp}\\
			       &= \sum_{i=1}^n \mu &\notag\\
			       &= n\mu,
  \end{align}
  where in \eqref{eq:lin_exp}, we have used linearity of expectation.

Notice each point. Use labels to equations when you want to explain that particular step. If you have routine simplifications or it is obvious, there is no need to explain that. Use \notag if you do not want that particular step to be numbered.

In general, avoid having more than 4-5 lines in a single align environment. Any more than that and it becomes too difficult for the reader. Break the sequence of steps into small chunks of 3-4 lines each, and add some text in between each chunk (explaining some of the steps on the way). When you have to write a technical document with a page limit, skip all steps that are routine simplifications. However, make sure that you have a separate document with all the steps, even if this is just to convince yourself that everything is right.

• When you are using a particular bound, be very specific. Unless it is something very basic (like linearity of expectation), refer to a specific lemma or equation that is listed somewhere in the document.
• Sometimes, you will want to refer to a specific lemma/theorem which was proved in a different paper. If you make use of this repeatedly, it helps to state this explicitly in your document, like

\begin{theorem}[Lemma 2, \cite{some_paper}]
If $X$ is a log-concave random variable and $f_X$ denotes its probability density function, then there exist positive numbers $\alpha,\beta$ such that
\[
 f_X(x)\leq \beta e^{-|x|/\alpha}
\] 
for all $x\in\mathbb{R}$.
\end{theorem}

If you only use a particular lemma once or twice, or you are very restricted in terms of space, simply refer to the result from the paper when needed, using \cite[Lemma 2]{some_paper}.

• Mathematical/technical mistakes can be more catastrophic than grammatical errors. These can sometimes even lead to rejection of a paper and should be absolutely avoided.
• Avoid overusing \(\cdot\) for the product of two terms. Putting some extra space or reordering terms can sometimes give a better effect. For example, instead of \(\int f(s)\cdot s ds\), you can use \(\int sf(s)ds\), or if you want some extra space between terms, use \hspace{2pt} or something similar.

• To present numerical results, use graphs or tables. When plotting graphs, be sure to use thick lines, markers (if number of points is not too much), and turn the grid on. If there are multiple curves in one plot, then there should be a legend, and each curve should be labeled appropriately. The x and y axes should always be labeled. Use labels that are descriptive but not too long.
• Pictures are worth a thousand words. A single good figure can sometimes explain a concept better than a page of text. Always put some thought into creating figures. Make sure that notation is consistent with what is there in the rest of the document.
• Avoid too much color. Keep in mind that some journals/conferences charge extra for color figures, so in those cases it is good to keep figures in black-and-white. For plots, you can use linespecs (dotted, dashed, continuous, etc) instead of different colors. Also keep in mind that some readers might print your paper in black-and-white and the color information is lost. For documents that are not conference/journal papers, it helps to have some color (but not too much) as this can produce a good effect. This is particularly the case for presentations, theses, reports, etc.
• Captions for figures/tables/plots should be descriptive. They should clearly explain what is being presented. When you have a figure, make sure that it is being referred to somewhere in the paper.

• The Chicago manual of style
• Mathematical writing by Don Knuth, Tracy Larrabee and Paul Roberts.
• "How to write Mathematics" is an excellent article by Paul Halmos on writing articles or papers.
• Some advice on research and writing.
• Henning Schulzrinne has compiled some tips for writing papers, common writing bugs, and writing reviews. Some more resources here.

---

---