This is an idiosyncratic list of what I consider “best practices” when writing $\LaTeX{}$ documents. I primarily write documents for teaching, so the focus of this advice is generally towards teaching materials. Elsewhere, I have a list of Common $\LaTeX{}$ Errors.
I highly recommend hand-writing a first draft of any document which you intend to typeset. Preferably, use pencil and paper. You will definitely need to erase and re-write things. I recommend this practice because the work of typesetting things in $\LaTeX{}$ is sufficiently complicated that you don’t want to mix it with the act of composition. Separate composition and typesetting as far as possible.
Mary-Claire von Leunen has a great bit about this in A Handbook for Scholars.
$\LaTeX{}$ doesn’t care how much white space or indentation you use, but it can make things much more readable. Here is a nice algebra fact from highschool.
\[ (x+y)^2 = xx + xy + yx + yy = x^2 + 2xy + y^2 \]
There are lots of ways to typeset this equation. Looking at it on paper, your natural instinct is to code this in $\LaTeX{}$ as follows.
\[ (x+y)^2 = xx + xy + yx + yy = x^2 + 2xy + y^2 \]
However, this approach makes it hard to modify the equation. Maybe you notice a weird typo in the middle and want to modify it. Or you want to add brackets. You wind up having to count how many equal signs deep you are to determine which equation to edit. It’s a mess. Now, look at the following snippet of $\LaTeX{}$ code.
\[
(x+y)^2
= xx + xy + yx + yy
= x^2 + 2xy + y^2
\]
Every equation is on its own line of code. You can see each part clearly. If you want to modify a whole equation, you can (usually) just double click on the line to select it. Even though the typeset version doesn’t feature these line breaks1, it helps to have them on the code level. Of course, you should put simple display style equations on their own line. \[ 1 + 1 = 2 \] Should appear in your code as:
\[ 1 + 1 = 2 \]
Pad it with lots of space on either side, so that it stand out. My colleague Ivan Khatchatourian like to put a tonne of spacing between section and page breaks, so that they visually stand out when viewing the code.
Another feature, not to be overlooked, is the ability to add indentation. Nesting everything with lots of levels of indentation can make your $\LaTeX{}$ more readable and maintainable. Here is another example.
\[\left[\begin{array}{cc}1&2\\3&4\end{array}\right]\]
This is a perfectly fine $2 \times 2$ matrix. This sort of things crops up all the time in linear algebra. $\LaTeX{}$ won’t care if you code it in the following terrifying manner. (Please, never write code like this.)
\[\left[\begin{array}{cc}1&2\\3&4\end{array}\right]\]
The computer will happily typeset anything that’s syntactically valid. But, that example is a hard to read and maintain. Compare it with the following.
\[
\left[
\begin{array}{cc}
1 & 2\\
3 & 4
\end{array}
\right]
\]
With a lot of levels of indentation, you can see exactly what is going on. It is clear what the entries in the matrix are. It is clear what kinds of brackets you are using. Everything is much clearer with lots of indentation.
Leaving comments for yourself is underrated. It is incredibly helpful for keeping track of how the document came to be. For example, you can leave a link when including a computation from WolframAlpha. You might want to have students factor $x^2 - 5x + 6$. In your write-up of the solutions, you could code:
\[
x^2 - 5x + 6
= (x - 2)(x - 3)
%% Wolfram: https://www.wolframalpha.com/input?i=factor+the+equation+x%5E2+-+5x+%2B+6
\]
Or, if you’re including a graph from Desmos, you can include link to the original graph. This lets you go back and fiddle with the original graph if you need to modify the lesson plan later.
\[
\begin{center}
%% y = x^2 - 5x + 6
%% https://www.desmos.com/calculator/mtaiybb6l0
\includegraphics[width=0.5\textwidth]{quadratic.png}
\end{center}
\]
A little bit of copy and pasting during the typesetting phase can save a lot of work re-creating graphs later.
You can, of course, use comment to leave little notes for yourself. I like to use tk to let myself know where these notes are, as it is very rare2 in English and thus easy to search for. I’ve surprised myself by writing whole sections of lesson plans as comments. It is a happy day when you find such comments, and save yourself a tonne of work.
It is entirely possible to use $\LaTeX{}$ as is without customization. There are some things that you won’t be able to do, but the documents you write will be perfectly reasonable. However, you can get a lot of functionality by defining a few macros and bundling them in to a style file.
Don’t be afraid of defining new commands.
If you find yourself writing \mathbf{i} ten times then it would be worth adding:
\newcommand{\ii}{\mathbf{i}}
to your style file and using \ii from then on3.
If I’m making a bunch of documents with a similar layout, I will even “abstract out” certain key pieces of information in to macros. For example, in a series of worksheets, I would put the following in my preamble:
\newcommand{\WeekNumber}{3}
\newcommand{\CourseTitle}{MAT A29: Calculus I for Life Sciences}
\newcommand{\CourseTerm}{Fall 2024}
\newcommand{\WorksheetTitle}{Limits to Infinity}
This centralizes all the information about the worksheet, and makes the layout less susceptible to copy and paste errors.
One surprisingly useful command to define is:
\newcommand{\ignore}[1]{}
This command ignores anything that you put it in to.
The code \ignore{typo} will leave your final document typo free!
Thanks to Ivan Khatchatourian
for reading a draft of this note and suggesting the wide spacing around section breaks and the populatization of \ignore{}.
This idea of adding line breaks on the code side actually runs much deeper. People like adding semantic line breaks to help make mark-up more readable. Kernighan wrote about this idea in 1974 in UNIX for Beginners. Buckminster Fuller wrote this way in the 1930s. ↩︎
Sasha Chapin pointed out that ‘tk’ doesn’t even appear in the word tchotchke, which is about the only place I would think to look for it! Someone else, I regret that I forget who, pointed out that it occurs in Atkin which would come up fairly often if you write about health or dieting. My colleague Tom Kielstra was bewildered to find his initials everywhere in my code; he thought all the tk’s were personal to-dos for him. ↩︎
My colleague Tyler Holden disagrees with me about this particular choice of $\LaTeX{}$-nical convention.
He thinks that one should write \bf i instead of \ii.
This is the sort of thing that we squabble about.
We’re gigantic nerds. ↩︎
Published: Aug 14, 2024
Last Modified: Aug 23, 2024
Thanks for reading! If you have any comments or questions about the content, please let me know. Anyone can contact me by email.