**Common mistakes in technical writing** **[Wojciech Jarosz](https://cs.dartmouth.edu/~wjarosz/)**

Dartmouth College

(This is a living document) Last update: 7 April 2021 When reviewing papers I often see the same mistakes pop up over and over. Some of these are conceptual (e.g. not motivating the approach properly, being aggressive towards previous work) while others are technical things that are actually much easier to fix (improper use of parenthetical citations and other $\LaTeX$ specifics). This document is my attempt to collect all of these common mistakes into one place for reference. While this is geared largely towards my area of focus (computer graphics), some of these concepts may carry over to other technical disciplines. If you are my student, learn this list and don't send me a draft for review with any of these avoidable mistakes. Conceptual mistakes =================== 1. **abstract != intro**: An abstract and an intro are alternate paths into the paper. The abstract is a self-contained, concise summary for *experts*. An intro is the gentler path motivating the problem for a more general audience. For example, the abstract can be written for rendering experts, while the intro is written for people in graphics or maybe even computer science. The abstract and intro are therefore expected to be redundant, but due to their different functions it is rare that you'll really be able to verbatim copy from one to the other (this is acceptable, but discouraged). Read [this](https://www.lightbluetouchpaper.org/2007/03/14/how-not-to-write-an-abstract/) and [this](http://people.csail.mit.edu/fredo/PUBLI/writing.pdf). 2. **don't just describe related work, *relate* it!**: All too often while reviewing a paper the related work section describes the prior methods extensively, but gives no indication of how these methods relate to the problem addressed in the paper, how they differ from the proposed solution, and what are the practical consequences of these differences. Your related work section shouldn't just describe the other approaches, it should clearly relate these to your approach. 3. **don't bash previous work**: Be thorough but respectful, and keep in mind that your context might be slightly different than theirs. Also, the authors will likely be reviewing your paper. 4. **be clear about your assumptions/limitations**: You may be concerned that this may make your method seem less impressive or incremental, but, from my personal experience, I place much more trust in the authors if they appear forthcoming about their limitations and assumptions, and don't try to over-claim. Also, manage expectations from the beginning. Don't assume that clearly listing limitations at the end compensates for overselling in the intro. This just leads to disappointed reviewers. 5. **create a meaningful overview, or don't bother**: The overview should not be a table of contents in paragraph form. If your overview contains nothing beyond what can be obtained by skimming the section headings, then don't include it. Instead, interleave these forward section references into the intro or into a functional description of the components of your method/system/approach, if it has many parts. 6. **a conclusion is not an introduction in past tense**: Reflect on what you have created/proposed, its advantages and limitations—especially things that were difficult to discuss without the reader already knowing the details of your approach. 7. **in a rebuttal, clarify and reassure**: Being aggressive towards reviewers who you disagree with or feel are ignorant very rarely works (I have made this mistake before). If you disagree with a reviewer, be firm, but always polite. If you need to, write your angry rebuttal first, and then write your real rebuttal. You have three important goals during a rebuttal: 1. clarify any misunderstandings or factual errors in the review, 2. commit to improvements and changes, and 3. convince the reviewers that you are *capable* of making these changes and will be *cooperative* during the shepherding process. Technical mistakes =================== Grammar & Language ------------------- 8. **hyphenation**: Use hyphens for compound adjectives such as: hard-working, camera-ready, bad-tempered, computer-aided, etc. Unfortunately, sometimes the same set of words are hyphenated, and other times they aren’t, depending on context. For instance, in the example “This material has a strong single-scattering component.” “single-scattering” forms a single compound adjective describing “component”, so it needs to be hyphenated. On the other hand, in the example “This material has strong single scattering”, it is not hyphenated since “single” is the adjective describing the noun “scattering”. Other context-dependent examples include “high-performance” vs. “high performance” or “real-time” vs. “real time”. An exception to the rule is if the first word is the adverb “very” or ends in “ly”, such as in “physically based rendering”, you don’t use a hyphen. 2. **dashes**: English uses three different types of dashes: the hyphen (-, produced with one dash `-`), the en-dash (–, produced with two dashes `--`), and the an em-dash (—, produced with three dashes `---`). These each have different grammatical uses. Hyphens are used for most interword dashes, e.g.: “non-negligible”. You should use the en-dash to indicate an opposition or relationship, e.g.: `mass--energy equivalence` → “mass–energy equivalence”; or for year, number or page ranges, e.g.: `as seen on pages 17--30` → “as seen in on pages 17–30”. En-dashes (surrounded by spaces) or em-dashes (without spaces) can be used to denote a break in a sentence or to set off parenthetical statements, as in: “A flock of sparrows – some of them juveniles – flew overhead.”, or “A flock of sparrows—some of them juveniles—flew overhead.” 3. **latin abbreviations**: Understand what the various latin phrases mean, and learn how to typeset them correctly. Common Latin abbreviations should **not** be italicized. 1. **et al.**: has no period after the “et”, but does have a period after “al.”. You can read this as “and others” in English. Use this only when referring to two or more additional authors. 2. **e.g. vs. i.e.**: these two are **not** interchangeable. From [Paul Brians](http://public.wsu.edu/~brians/errors/e.g.html): “When you mean “for example,” use “e.g.” It is an abbreviation for the Latin phrase *exempli gratia*. When you mean “that is,” use “i.e.” It is an abbreviation for the Latin phrase *id est*. Either can be used to clarify a preceding statement, the first by example, the second by restating the idea more clearly or expanding upon it.” As a mnemonic device, you could think of “e.g.” as roughly “example given”, and “i.e.” as “in effect”. 3. **etc**: don’t add an “etc.” at the end of a list of examples initiated with “e.g.”. 4. **cf.**: translates to, and can be read aloud as, “compare”. Its purpose is to compare the immediately preceding statement with another statement in the same work or more commonly, a statement in another work. In English writing, do not use cf. to mean “see”. 4. **spaces**: TeX has several rules to automatically adjust the size of spaces in different contexts. It, for instance, creates a longer space after a period “.” unless it follows a capital letter. If you have a period mid-sentence (like in “et al.”) you need to instruct TeX to use a regular space: `et al.\ `. If an uppercase letter ends a sentence, you need to use a `\@` before the period. 5. **the/a**: For non-native speakers, a very common mistake is improper use of “a” and “the”. Sometimes you need one, sometimes you need the other, and sometimes you need neither. A common non-native sounding example I’ve seen involves “GPU”: “Ray tracing on GPU” (sounds much more natural if “a” or “the” is included between “on” and “GPU”). 6. **few/a few/quite a few**: Surprisingly, including or omitting the “a” before “few” can completely change the meaning of a sentence. Compare “Tom has a few oranges he is willing to share.” with “Tom has few oranges he is willing to share.” The first suggest that Tom is willing to share some oranges, the second rather suggest that Tom doesn’t have many oranges to share. “A few” really means “some”, and emphasizes the *existence* of some (small) quantity, while “few” emphasizes that the quantity is *small*. Another way to think of this is that “few” = “only a few”, so the latter is actually saying: “Tom has only a few oranges he is willing to share.” Additionally, “quite a few” actually means “many” or “a surprisingly large number”. 7. **cannot/can not, maybe/may be**: Both “can not” and “cannot” are acceptable, but they are used slightly differently. In particular, you would use “can not” if the “not” doesn’t belong to the “can” but rather to the words following, such as the construction “not only”: “He can not only sing, but also dance.” Likewise “maybe” and “may be” are both valid, but are not interchangeable. “Maybe” means perhaps whereas “may be” indicates a possibility, e.g.: “He may be smart, or maybe he is just lucky.” Math & Numerics ---------------- 15. **basics quick-reference**: [This MathJax tutorial](https://math.meta.stackexchange.com/questions/5020/mathjax-basic-tutorial-and-quick-reference) is a great quick reference for your most common LaTeX math typesetting needs. 2. **learn AMSmath and use it**: Read the [AMSmath documentation](ftp://ftp.ams.org/ams/doc/amsmath/amsldoc.pdf) and the [Short Math Guide](ftp://ftp.ams.org/pub/tex/doc/amsmath/short-math-guide.pdf) to get started. I very rarely use the standard `equation` environments anymore. My default environment is `align`, which basically acts as a drop-in superset replacement for `equation`. Learn to use the `cases` environment. 3. **notation & macros**: Define macros (with descriptive names) for all your repeatedly-used notation. If you do this consistently, it makes it much easier to experiment with and perfect your notation while working on the paper. Using search and replace or manually hunting down each instance are both very error prone. 4. **number all equations**: Your reviews and your future self will appreciate it. It is much easier to discuss details of the paper when you can say e.g.: “The x we solve for in Equation 3 is the same as the x that appears on the right-hand-side of Equation 13”, instead of: “The x we solve in the first unnumbered equation of the second column of page 4 is the same as x that appears on the right-hand-side of the unnumbered equation between Equations 12 and 13”. You will run into this not only during review, but also many years down the road when someone emails you asking for clarification about some detail in the paper. 5. **equations are parts of sentences**: All equations (displayed or inline) should grammatically be part of a sentence. This means that you will typically need some punctuation before a displayed equation (a comma or colon, depending on context), and possibly punctuation after (a period or comma) if the surrounding sentence continues. As a simple rule, never forget a period after an equation, and never create a dangling displayed equation by placing a period directly beforehand. You can often figure out what punctuation (if any) is needed before a displayed equation by reading the equation out loud in the context of the entire surrounding sentence. 6. **multi-letter sequences in equations**: Sequences of letters intended as words or abbreviations will not be typeset properly inside math environments. This is because LaTeX interprets each letter in a math environment as a separate mathematical entity, typesetting it appropriately (with a different font, and, more importantly, with more spacing between each symbol). There are several common situations to consider: 1. **multi-letter variables**: In most cases, you should avoid using multi-letter symbols since it is rather non-standard, but if you must, and it will be clear within the context, you should enclose your multi-letter variables with `\textit`. 2. **custom functions**: LaTeX defines several standard math functions or operators (e.g. `\sin`, `\cos`, `\exp`, `\log`, etc) which are typeset and spaced differently than variables. If you want to define a custom, multi-letter function `\xxx` that is typeset in the same way as `\sin`, you should do this with: `\DeclareMathOperator{\xxx}{xxx}`. There are other variants and options, check the AMSmath [documentation](ftp://ftp.ams.org/ams/doc/amsmath/amsldoc.pdf). 3. **short phrases**: If you want to interject a word or phrase into a displayed equation enclose it with `\text`, e.g.: use ~~~ $$f_i \text{ is monotonic,} \quad i = 1,\dots,c+1$$ ~~~ which produces: $f_i \text{ is monotonic,} \quad i = 1,\dots,c+1$, as opposed to ~~~ $$f_i is monotonic, \quad i = 1,\dots,c+1$$ ~~~ which produces: $f_i is monotonic, \quad i = 1,\dots,c+1$. This will use the document's standard text font. 4. **abbreviations**: Sometimes you want to include a word or abbreviation, which should be part of a mathematical symbol (for instance in a subscript or superscript), but should be typeset with standard word spacing. You could use the `\text` command like above, but if you want to use and control the math font, you can use `\mathit` (math italics) or `\mathrm` (math roman) instead, e.g.: `$L_\mathrm{max}$`, not `$L_{max}$`. 7. **negative numbers**: In text mode, the “`-`” is interpreted as a hyphen, which doesn’t look right when typesetting negative numbers. Typeset negative numbers using math mode, e.g.: `$-1$`, instead of `-1`. 8. **angle brackets**: Use `\langle` and `\rangle`, instead of the comparison operators `<` and `>`, when you want angle brackets. 9. **big parentheses**: Learn how to use properly sized parentheses pairs. You can have LaTeX choose the size of the delimiters automatically by using the `\left` and `\right` paired commands, e.g.: `\left(\frac{1}{2}\right)`, instead of `(\frac{1}{2})`. These must always be used in pairs and they don’t work across line break. If your parenthetical block spans multiple lines, you must include an invisible `\right.` or `\left.` counterpart before the linebreak. Sometimes the automatic sizing is not ideal, in which case you can fine-tune with manual sizes: `\bigl`, `\Bigl`, `\biggl`, `\Biggl` (and the r counterparts). Since these are static sizes, you don’t need to take special care with multi-line equations. All of these work with round (), square [], and angled `\langle` `\rangle` brackets as well as vertical bars `\vert` and `\Vert`. Citations & References ----------------------- 24. **citations as nouns**: Never, ever, ever use parenthetical citations as nouns, e.g.: never write anything resembling: “As explained by [Kajiya 1986]”; instead write: “As explained by others [Kajiya 1986]”, or, even better: “As explained by Kajiya [1986]” (see `\citet` below). They are called *parenthetical* citations for a reason: they should be *parenthetical*. As a general rule of thumb, **if you remove all parenthetical citations from the paper, you should still have complete, grammatically correct sentences**. This looks particularly obnoxious and obvious when you have numerical or superscript citations like “As explained by [1]” or “As explained by¹”. Even if you are referring to the book or article itself, instead of to the authors, you should not use citations as nouns, e.g. don't write: “More information can be found in standard textbooks such as [Pharr and Humphreys 2010]”. 2. **citing with LaTeX:** 1. **spacing**: Use a non-breaking space `\~` between a citation and the preceding word in the sentence: ~~~ Path tracing~\cite{Kajiya:86} is... ~~~ 2. **citet, citep, citeauthor, citeyear**: The [natbib](http://www.ctan.org/pkg/natbib) package (included in recent versions of the acmart/SIGGRAPH LaTeX template) provides different cite commands for textual (`\citet{citekey}`) and parenthetical (`\citep{citekey}`) citations, as well as the ability to list just the author (`\citeauthor{citekey}`) or just the year (`\citeyear{citekey}`) of the citation. Learn and use these variants. These allow you to, for instance, use the author name as a noun in the sentence, but avoid redundancy with the information in the parenthetical citation, e.g.: instead of “As explained by Kajiya [Kajiya 1986]” or “As explained by [Kajiya 1986]”, you can write “As explained by Kajiya [1986]” with the syntax ~~~ As explained by \citet{Kajiya:86}. ~~~ Unfortunately, the current EG/CGF style seems incompatible with natbib, but it does allow using biber/biblatex, which provides the `\textcite` command and many more. 3. **multiple citations**: Place a sequence of multiple citations into one `\cite{key1,key2}` command with cite-keys separated by commas, instead of separately as `\cite{key1}\cite{key2}`, e.g.: ~~~ Bidirectional path tracing~\cite{Veach:94,Lafortune:93}. ~~~ 3. **The bibliography**: I maintain a large master [rendering-bib](https://github.com/wkjarosz/rendering-bib) file with thousands of rendering-related references on github. Grab it and read the tips on usage. 1. **correct online bib entries before use**: Most digital libraries are notoriously bad at providing correct bibtex information. The ACM digital library is no exception. Always check when you cut-and-paste any online entry into your bib file. Common errors include: 1. page numbers should be separated by an en-dash, e.g.: ~~~ pages = {195--200}, ~~~ and not ~~~ pages = {195-200}, ~~~ 2. DOI entries should include just the number, and not a full URL, e.g.: ~~~ doi = {10.1145/1964179.1964185}, ~~~ and not ~~~ doi = {http://doi.acm.org/10.1145/1964179.1964185}, ~~~ If you are short on space, generate a [shortdoi](https://shortdoi.org), which would [produce](https://shortdoi.org/10.1145/1964179.1964185) the more compact: ~~~ doi = {bv5xdk}, ~~~ 3. incorrect title and venue capitalization. 2. **capitalization in reference titles**: Resist the temptation to force capitalization by enclosing all your bib entry titles in double braces: `{{My Title}}`. *It is the bib style’s job to decide on the capitalization of titles, not yours*, as this varies between publication venues. However, you do need to inform BibTeX when certain words must be capitalized, for instance if they are acronyms or proper names. Do this by enclosing just the capitalized letters in braces: ~~~ title = "Fast {GPU} ray tracing of dynamic meshes using geometry images", ~~~ To capitalize, wrap the entire word: ~~~ title = "Exact evaluation of {Catmull}-{Clark} subdivision surfaces at arbitrary parameter values", ~~~ instead of just the first letter `{C}atmull-{C}lark` as the latter can cause kerning issues. See the [TeX FAQ](http://www.tex.ac.uk/cgi-bin/texfaq2html?label=capbibtex). 3. **multiple author/editor names**: Author names should be separated by "and", and not by a comma ",". Otherwise BibTeX will think they’re all part of the same author, with a very long name, e.g.: write ~~~ author = {John Doe and Jack Doe and William Doe and Averell Doe} ~~~ and not ~~~ author = {John Doe, Jack Doe, William Doe and Averell Doe} ~~~ This also applies to editor names. 4. **consistency**: Be consistent about how you format the information across different bibliographic entries, e.g.: don’t write “Proceedings of EGSR” in some entries, and “Proceedings of the 18th Eurographics Symposium on Rendering” in another. On the other hand, many conferences have complex publication histories and different time periods therefore should be cited differently. Learn the ones important to you (see below) and use my [rendering-bib](https://github.com/wkjarosz/rendering-bib) files. 5. **use predefined strings**: A good way to ensure consistency is to leverage BibTeX’s ability to predefine and reuse strings. In the [rendering-bib](https://github.com/wkjarosz/rendering-bib) project I maintain a separate `strings-full.bib` file which defines commonly used strings like journal names. The syntax is: ~~~ @string{eg = {Computer Graphics Forum (Proceedings of Eurographics)}} ~~~ If you include this in your project before your main BibTeX file, ~~~ \bibliography{strings-full,rendering-bibtex} ~~~ then any entry published at Eurographics can simply list `journal = eg`. You can add any additional entries into a separate `additional.bib` file and use: ~~~ \bibliography{strings-full,rendering-bibtex,additional} ~~~ A benefit of putting the string definitions in a separate bib file is that you can redefine the venues and publisher strings to abbreviated version by creating a `strings-abbrv.bib` file (e.g. when needing to squeeze space for submission), and issuing: ~~~ \bibliography{strings-abbrv,rendering-bibtex,additional} ~~~ instead. 6. **know the publication history**: Many conferences have gone through a complex evolution of their publication history. For instance, EGSR was sometimes published as a book called “Rendering Techniques”, but in 2008 it became a special issue of the Computer Graphics Forum journal. The proper way to cite a paper from EGSR therefore depends on the year. The same applies to SIGGRAPH and Eurographics. Nicolas Holzschuch summarizes the history of [SIGGRAPH](http://maverick.inria.fr/Membres/Nicolas.Holzschuch/siggraph.html), [EG](http://maverick.inria.fr/Membres/Nicolas.Holzschuch/eg.html), and [EGSR](http://maverick.inria.fr/Membres/Nicolas.Holzschuch/egsr.html) well. Again, the [rendering-bib](https://github.com/wkjarosz/rendering-bib) project includes this for graphics/rendering venues. Other best practices --------------------- 27. **don't commit generated files in svn/git**: There are many files that are generated during building either LaTeX or code. Don't commit these files to the repository as it will cause conflicts for your collaborators. This includes the generated PDF or executable! Other common generated files in LaTeX include: `.aux, .bbl, .blg, .fdb_latexmk, .fls, .log, .out, .synctex.gz` files. 2. **split into multiple files**: Split your LaTeX document into multiple files at conceptual breakpoints. For a journal paper you would likely create a different .tex file for each major section. This allows multiple people to work on the paper while reducing svn/git merge conflicts. The main .tex file should basically only have the preamble, title, and `\input` the various additional files. Remember that you likely want `\input` and not `\include`, which forces a `\clearpage` before and after. To play nice with some editors (e.g. TeXShop) list the root tex file as a special comment at the top of all dependent tex files. For instance, if your main file is `mypaper.tex`, include `%!TEX root = mypaper.tex` as the first line in all child files. 3. **put graphics in a subfolder**: Pretty simple. Don’t pollute your root tex directory with all your graphics and figures. 4. **caption placement**: The caption for a figure should appear below; for a table, above. Just place the `\caption` command above or below the content. 5. **use consistent references**: Choose a naming scheme for various types of references and stick to it consistently, e.g. a 3-letter prefix: `sec:section-name`, `fig:figure-name`, `eqn:equation-name`, `tab:table-name`, `alg:algorithm-name`, etc. 6. **avoid hard wrapping**: Everyone has different sized displays and windows, don’t force your size on your collaborators. Use soft wrapping. It is a nightmare to visually parse the LaTeX source for a file with mixed wrapping. Some people find it useful to write each sentence on a separate line to make diffs and merges easier. This is acceptable, but shouldn’t really be necessary with a good diff tool. 7. **in-file commenting**: Establish some macros for in-file commenting and communication between your co-authors. For example, you can define a macro named after each author’s initials (e.g. `\cWJ{Wojciech’s comment}`) for adding comments into the text. These comments can be simple colored text (it can also be useful for each author to have a different color) or using a pdf commenting package (see below). Regardless of the type of comment, it is also useful to provide an easy switch to turn all comments off (so you don’t accidentally submit for review with a stray comment still lingering). 8. **acknowledgements**: Keep track of people that helped you during the course of your research. Did someone (not involved in the project) help you make a figure, or did anyone provide narraration for the supplemental video? Did someone have a discussion with you that helped you overcome some hurdle? This support network is important to acknwoledge, but easy to overlook when submitting the final version. It is probably reasonable to always acknowledge the lab/group you work in, but sometimes it may make sense to also call out specific individuals. I recommend you insert comments directly into your LaTeX file in the acknowledgements section so when you get to writing this you have all the info there. 9. **funding sources**: If I am funding you, ask me for any potential funding acknowledgements to include before submitting the camera ready version. 10. **wrap displayed equations with comments**: If you include an empty line before or after a displayed equation you will introduce a paragraph break, which is often unintended. Depending on the style this will also sometimes indent the subsequent text. Don’t use `\noindent` to fix this! Instead, avoid the blank lines in the source that cause the paragraph breaks. To provide visual separation for the displayed equations in the tex file, I find it helpful to prefix and postfix each displayed equation with a few commented blank lines: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ tex linenumbers The equation % % \begin{align} y &= x^2, \end{align} % % is simple to solve. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 11. **figure sizing**: Whenever possible, avoid excess white space on the sides of your figures. You can size your graphics in LaTeX using the defined lengths `\textwidth` (for double-column figures) or `\columnwidth` (for single-column). 12. **line numbering**: Many venues provide line numbers in the review version of their LaTeX style. Don’t forget to enable this. It is immensely frustrating as a reviewer to not be able to refer to specific locations of the paper by line number. 13. **useful LaTeX packages:** + **proper tables**: Use the [booktabs](http://www.ctan.org/pkg/booktabs) package for creating publication-quality tables and read the [documentation](http://mirrors.ctan.org/macros/latex/contrib/booktabs/booktabs.pdf). As a general rule of thumb, if you have vertical lines in your table, you are likely doing something wrong. + **units**: When typesetting values with units, should you use italics (10 *m*) or Roman (10 m) fonts for the units? Should you put a space (10 m) or no space (10m) between the value and the corresponding unit? Use the [units](http://www.ctan.org/pkg/units) package and it will do the right thing. The general form is `\unit[val]{dim}`, so for 10 m, you would have `\unit[10]{m}`. This also includes nice fractions. See the [documentation](http://ctan.math.washington.edu/tex-archive/macros/latex/contrib/units/units.pdf). + **intelligent cross-referencing**: With the [cleveref](https://ctan.org/pkg/cleveref?lang=en) package you can use a single `\cref{label}` command for any type of cross-reference, and it will automatically produce "Equation (3)" or "Section 4.1" depending on whether `label` refers to an equation, or section, etc. + **pdf comments**: I often use the [pdfcomment](http://www.ctan.org/pkg/pdfcomment) package for in-text PDF annotations. This can be useful for communicating within the tex file with your co-authors. + **typography extensions**: The [microtype](http://ctan.org/pkg/microtype) package incorporate a bunch of micro adjustments to make the typography easier to read and more beautiful. As an added bonus it also tends to shorten the paper slightly due to differences in line wrapping. + **xspace**: The [xspace](http://www.ctan.org/pkg/xspace) package allows you to define macros that interact properly with surrounding spaces and punctuation. Other resources =============== For further reading, take a look at many other useful resources online discussing similar topics: - - - - - - - - - - -