Home

Awesome

Advice for writing LaTeX documents

Introduction

If you're writing a scientific book, a paper, or a thesis in computer science, engineering, mathematics, physics or a related field, it pays to write it using LaTeX, especially if your work contains formulas, symbols, and heavy cross referencing. Here is advice for doing so, collected over decades of writing hundreds of papers and books, mostly using LaTeX.

Note that this list is not intended to provide advice on English writing style, scientific writing, or TeX programming. There are many other excellent guides for all these topics.

Contributions to this guide via GitHub pull requests are always welcomed.

Put the document under version control

Write readable and maintainable LaTeX source code

Obtaining metrics from large code bodies is difficult
for technical and operational reasons~\cite{Moc09,GS13}.
On the technical side,
code dependencies make it difficult to establish
the full context needed in order to parse and semantically analyse the code.
This is especially true for C code,
where the compilation depends on
system header files,
compiler-defined macros,
search paths, and
compile-time flags passed through the build process~\cite{Spi03r,LKA11,GG12}.
The operational reasons are associated with the required throughput,
though due to the relatively small number of releases we examined,
this was not a major issue in this study.
% Advantages of model-based development {{{3

Automate the document build

Ensure that the document can be built with a single command, and that files that are out of date are appropriately rebuilt. This saves you from repeatedly executing multiple commands, makes it easier to work as a team, and avoids the accidental use of outdated files. You have the following options here.

Use continuous integration

Once you have automated your build, you are ready for the next step: continuous integration (CI) for LaTeX documents. Executing an automated build on every commit allows you to easily spot accidentally forgotten auxiliary files such as images or tables. You can also easily isolate changes that broke the build and that are sometimes hard to debug later. Moreover, CI creates a defined way to build your project, on which every collaborator can rely on.

You can automate this process using the github-action-for-latex GitHub Action, or the travis-ci-latex-pdf solution for Travis CI.

While at it, consider integrating the running of linters into the build process.

Automate the management of bibliographic references

Use style files

Conference organizers and publishers often supply style files that determine the appearance and formatting of a document and its references. Download them and use them. If you're writing a thesis and your institution doesn't provide a template you can use this one. Seeing your document in its published look boosts your motivation, helps you appreciate how your readers will experience it, and minimizes rework by forcing you to comply with the publisher's requirements while you develop your document.

Use third-party LaTeX packages

You can obtain many formatting goodies by incorporating into your document third-party LaTeX packages. Most LaTeX distributions provide a package management system that simplifies the installation and maintenance of packages. Here are some popular LaTeX packages your may want to know about.

Avoid explicit formatting

\newcommand{\finding}[1]{\textbf{#1}}

while the following environment declaration will list a software's license in a small font keeping its formatting.

\newenvironment{license}{\verbatim\scriptsize}{\normalsize\endverbatim}

Use symbolic references

Mathematics

\[
E = mc^2
\]
This formula states that the equivalent energy (\(E\))
can be calculated as the mass (\(m\)) multiplied
by the speed of light (\(c\)) squared.
F_{n} =
  \cfrac{1}{\sqrt{5}} \left(\cfrac{1 + \sqrt{5}}{2}\right)^n
  - \cfrac{1}{\sqrt{5}} \left(\cfrac{1 - \sqrt{5}}{2}\right)^n
The atomic age started with the establishment of the mass–energy equivalence,
\[
E = mc^2 \,.
\]

Number and unit formatting

It took \qty{7146}{s} to load a \qty{134}{\gibi\byte} file over a
\qty{200}{\mebi\bit} connection over a distance of \qty{9500}{\km}.
During the transfer \num{12345} packets were dropped.
The ambient temperature was \qty{-35}{\degreeCelsius}.

Tables

tr -cs  & 1     & \X    & --    & \V    & 1 \\
sort w  & 0     &       & --    & \X    & 0 \\
fmt     & 1     & \X    & --    & \V    & 1 \\
tr A-Z  & 1     & \V    & 1     &       & 1 \\
sort -u & fmt   & \X    & --    & \V    & 1 \\
% Column labels
Command and options
        & Input requirements
                & Matched
                        & Connected
                                & Matched
                                        & Connected \\
\hline
% Data
tr -cs  & 1     & \X    & --    & \V    & 1 \\
sort w  & 0     &       & --    & \X    & 0 \\
...
\toprule
Header \\
\midrule
Table row 1 \\
Table row 2 \\
\bottomrule

Figures

Floats

Typography

LaTeX formatting

\usepackage{mathptmx}
\usepackage[scaled=.90]{helvet}
\usepackage{courier}

Writing

This guide focuses on LaTeX document preparation. Nevertheless, here is some advice for improving your writing and for avoiding common mistakes.

Additional material regarding LaTeX

Material on writing and presenting information

License

Creative Commons License

This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.