This living guide is a collection of best practices surrounding paper preparation, which grows every so often as I realize that I’ve given the same advice multiple times. All my students are required to read through this guide before distributing drafts, even internally. Addressing any issues incrementally avoids a last-minute scramble to fix them later.
Note: This guide is a work in progress.
Prefer to use small caps for acronyms. Full capital acronyms, like MDP or POMDP, tend to stand out in the text and draw the eye. Instead, using small caps—like \textsc{mdp} for \textsc is itself lowercase to achieve this effect. If you use the glossary package for acronym management, this becomes easier; see details below.
Using small caps isn’t always the best choice, especially when you inherit acronyms or, worse, mixed-case terms like LaTeX or ProcTHOR aren’t easily dealt with. I have done odd things before like \textsc{l}a\textsc{t}e\textsc{x}, which results in the unconventional
Using small caps isn’t always the best choice, especially when you inherit acronyms or, worse, mixed-case terms like LaTeX or ProcTHOR aren’t easily dealt with. I have done odd things before like \textsc{l}a\textsc{t}e\textsc{x}, which results in the unconventional
Know the difference between hyphens, en dashes, and em dashes.
- in LaTeX.-- in LaTeX.--- in LaTeX.Most style guides recommend not puting spaces around an em dash. The dash should touch the text on both sides, as I have done here.Most style guides recommend not puting spaces around an em dash. The dash should touch the text on both sides, as I have done here.
Never use double-quotes " in LaTeX; use single quotes and backticks. LaTeX is not designed to identify double quotes, so surrounding a word or phrase by quotes requires the following syntax: ``something''.
Punctuation goes before footnotes and closing quotes. Proper use looks like `something.' or bar.\footnote{A footnote.}.
Internal links should be neither colored nor surrounded by a colored box.
By default the hyperref package, upon which many other packages depend, tends to color internal links or puts colored boxes around links, which means that every use of \cite or \ref results in some ugly markup. These should be disabled. This fix can be achieved either during import \usepackage[hidelinks]{hyperref} or later with \hypersetup{hidelinks}.
Understand proper use of e.g. and i.e. Use e.g. for examples and i.e. for clarification. Both of these should be followed by a single comma and proceeded by either a colon, parenthesis, or an em dash—e.g., or surrounded as in this example—and never proceeded by a comma.
Enforce proper capitalization in BibTeX. Many BibTeX styles automatically update convert titles to sentence case, lower-casing many of the words. This behavior is by design, but does not play nice with acronyms. For example, a BibTeX entry with title = {DESPOT: Online POMDP Planning with Regularization} will produce “Despot: Online pomdp planning with regularization.” Instead, you can enforce capitalization with an extra set of curly braces around words you would like to preserve: title = {{DESPOT}: Online {POMDP} Planning with Regularization} will produce the correct “DESPOT: Online POMDP planning with regularization.”
Surrounding the entire title with additional curly braces will preserve capitalization for the entire title and is not recommended, since it will then over-enforce capitalization and thus deviate from the BibTeX-recommended style.
Surrounding the entire title with additional curly braces will preserve capitalization for the entire title and is not recommended, since it will then over-enforce capitalization and thus deviate from the BibTeX-recommended style.
Use a non-breaking space before references. The reference number should not begin a line, as it is both unpleasant asthetically and hurts readability. LaTeX uses the tilde character ~ to signify a non-breaking space, which allows a space between what it connects, yet will not break the line.
Stein \cite{stein}”Stein ~\cite{stein}” Note: This adds two spacesStein~\cite{stein}”You must manually maintain and clean BibTeX entries; Google Scholar and automated systems are imperfect. Simply downloading the BibTeX entries and using them will result in poor quality citations. Similarly, bibliography managers are not perfect. It is your responsibility to clean those entries.
Reference document elements in a way that matches the template: e.g., Fig. versus Figure. Many LaTeX templates are opinionated about how figures, tables, and algorithms are referenced. If the template displays “Fig. 1” when placing a figure, all mentions of that figure in the text should also read “Fig. 1” and not “Figure 1.”
In the final document, references must appear homogeneous. If you collected BibTeX entries from multiple locations, it is possible that you will have a mix of different ways to reference conferences or journals: e.g., “
Avoid using references as nouns. When referring to a paper, refer to the authors or to the algorithm rather than using the reference number. Instead of “[5] uses a novel approach.”, say “Stein and Roy [5] use a novel approach.” as this is both nicer to look at and also easier to follow.
When referencing a paper by its authors, the author names should not reappear in the citation. For example, “Work by Khanal and Stein (2024)…” is preferred to “Work by Khanal and Stein (Khanal and Stein, 2018).” Some citation packages have the \citet textual citation command, which will add the authors and year automatically. If that command is unavailable, manually typing the authors and using \citeyear is preferred. If the citation style is numeric and so does not use author names, this change is not needed.
Peer-reviewed venues should be cited over ArXiv versions. It is you responsibility to make sure your citations are up-to-date. Citing papers uploaded to the ArXiv is okay, but only if the paper has not be published elsewhere. Before a final submission, do a quick search for all ArXiV papers in your references to see if they have been accepted to another venue.
Equation subsubscripts must use \text for words or abbreviations.
When using subscripts that are words, enclose them with \text{} (or sometimes \textit{}) to ensure proper formatting and letter spacing. For example: V_{\text{known}} ($V_{\text{known}}$) is correct, while V_{known} ($V_{known}$) is not. Even when full words are not used, this may be an appropriate choice. Additionally, use text size commands—e.g., \tiny—to control the size of the text.
All equations should have a number and be followed by appropriate punctuation. This rule is fairly standard practice. All equations should have an equation number. They should also include punctuation as if they were part of the inline text. Thus, if the equation is the end of the sentence, it should be followed by a period, and a comma if the sentence continues.
Use Eq.~\eqref to refer to equations. Equations are often referenced in the text as “Eq. (1).” Using \eqref{eq:name} ensures that the equation number will be in parentheses. Using Eq.~\ref{eq:name} will result in “Eq. 1,” which is incorrect.
Max, min, argmax, and similar should be in body-text font and defined as operators. The \max and \min operators are built in and are in the body text font. For more complex and custom operators, the amsmath package provides support to define operators as follows: \DeclareMathOperator*{\argmax}{arg\,max}. Defining this as an operator means that the subscript will be placed below the middle of the text, which is expected behavior.
Prefer smaller .tex files, each added to a main file via \input.
It is often easier to navigate and edit smaller files than having a single massive file with all of the content in it. This guideline is particularly important when collaboratively editing via Overleaf, where jointly editing a single large file can lead to rendering issues in the editor.
Tables and figures should each get their own .tex file and added via \input.
It is almost always necessary to move around figures within the .tex document. Putting the code for figures and tables in their own files means they can be added via the \input macro and moved around with ease. I usually have a separate top-level folder called “inputs” that includes such files.
The glossary package should be used for managing acronyms and abbreviations.
The glossary package is incredibly useful for managing acronyms. For example, \newacronym{TAMP}{\textsc{tamp}}{task and motion planning} at the top of the file will expand \gls{TAMP} as “task and motion planning (
\usepackage[acronym]{glossaries-extra}
\glsdisablehyper % Avoid hyperref
\setabbreviationstyle[acronym]{long-short}
\setabbreviationstyle[short]{short-nolong}
\newacronym{POMDP}{\textsc{pomdp}}{partially observable Markov decision process}
\newacronym[category={short}]{PDDL}{\textsc{pddl}}{The Planning Domain Definition Language}
The glossary has helpful macros for other automatic formatting as well: \glspl will pluralize the acronym and \Gls will ensure the first letter is capitalized, useful at the beginning of the sentence.
The glossary has helpful macros for other automatic formatting as well: \glspl will pluralize the acronym and \Gls will ensure the first letter is capitalized, useful at the beginning of the sentence.
todonotes package for this. TODOTry to make the most of the space you have and avoid large white space. TODO
Prefer labeling figure elements to describing them in the caption. The reader should not be forced to glance back and forth between the figure and the caption to understand the figure’s meaning. Having labels for various items or subfigures appear near to the entities being discussed helps readability quite a lot. The tradeoff is that the figure becomes more cluttered, so use your judgment to maximize clarity.
Figure font families and font size should closely match those of the surrounding text. TODO
TODO: Always use software with a grid; powerpoint is not allowed for figure preparation.
TODO: figures should be made ‘in the size’ they will appear in the paper. TODO: doing so makes it easier to match font size.
When writing a draft, always start by using the template for the submission venue. TODO: important since it lets you format as you go and gives you an impression of the rough length of the document so far.
Construct results figures and captions while writing the results section. What figures you include are often defined by what you say in the writing and what you write will be defined by what results you decide to show. Relatedly, write figure captions as you write the body text, as crafting captions is similarly informative.
This guide’s section on Language Use is far from comprehensive. I strongly recommend purchasing Strunk & White’s famous Elements of Style.
This guide’s section on Language Use is far from comprehensive. I strongly recommend purchasing Strunk & White’s famous Elements of Style.
Ensure proper use of which vs. that. When used to describe or clarify something, which follows a comma while that never does.
Avoid an unqualified this in your writing. The word “this” is a deictic reference: its meaning depends on context. Rather than the potentially ambiguous “This can be overcome by […],” prefer to ground “this” to avoid the ambiguity: “This pervasive challenge can be […].”
Avoid using etc., particularly at the end of a sentence. I have been trying to avoid the use of “etc.” in general, since its use tends to be lazy writing. Prefer instead to clarify the point or say something a bit more descriptive, such as other items.
For work involving planning or reinforcement learning: know the difference between $Q$ and $V$. $Q$ takes two arguments; $V$ takes one. If you have more inputs, they should be grouped into a single object: e.g., $V(\{x, y, z\})$