main.tex

\documentclass[11pt,nonacm]{acmart}
\usepackage{silence}
  \WarningFilter{acmart}{\vspace should only be used to provide space above/below}
\makeatletter\let\@authorsaddresses\@empty\makeatother
\usepackage[T1]{fontenc}
\usepackage{href-ul}
\usepackage[tt=false,type1=true]{libertine}
\usepackage{amsmath}
\usepackage{natbib}
\usepackage{doi}
\usepackage{multicol}
\usepackage[nocn,noframes]{ffcode}
\usepackage{tabularx}
\usepackage[runs=2]{docshots}
  \docshotPrerequisite{main.bib}
\usepackage{xcolor}
\usepackage{paralist}
\usepackage{microtype}
\title{%
  \texorpdfstring
    {\includegraphics[width=1in]{hat.pdf} \\ Academic Writing in \LaTeX: \texorpdfstring{\\}{} Best and Worst Practices}
    {Academic Writing in LaTeX: Best and Worst Practices}}
\author{Yegor Bugayenko}
\usepackage{bibcop}
\pagenumbering{gobble}
\raggedbottom
\tolerance=2000
\setlength{\parindent}{0pt}
\setlength{\columnsep}{32pt}
\setlength{\parskip}{6pt}
\setlength{\headheight}{18pt}
\setlength{\footskip}{18pt}

\newcounter{hint}
\newcommand{\hint}{\refstepcounter{hint}\S\arabic{hint}: }

\begin{abstract}
This is a humble attempt to summarize most typical mistakes we
make while writing academic papers in \LaTeX{} and most important
recommendations. Each suggestion or a mistake takes a short paragraph of
description right here and also may suggest looking into a more detailed
explanation in some other online resource. We recommend, before submitting
your paper to a conference or a journal, go through this list of mistakes and
make sure none of them are present in your paper.
\end{abstract}

\begin{document}
\pagestyle{plain}
\date{\today}
\maketitle

\LaTeX{} sources of this document you can find in
\href{https://github.com/yegor256/latex-best-practices}{this GitHub repository}
and contribute your ideas through a pull request.

Beforehand, we suggest you read these:
\begin{itemize}
\item \href{https://developers.google.com/tech-writing/overview}{Technical Writing Courses by Google}
\item Book by \citet{zobel2004writing}
\end{itemize}

\hint
Check your \ff{.tex} sources with \href{https://www.ctan.org/tex-archive/support/lacheck/}{lacheck}
and maybe other tools.

\section{Preamble}

\hint
Use \href{https://ctan.org/pkg/acmart?lang=en}{\ff{acmart}} document style and read their \href{https://www.acm.org/publications/taps/latex-best-practices}{Best Practices}. Start the document with this:
\begin{ffcode}
\documentclass[11pt,nonacm,natbib=false]{acmart}
\settopmatter{printfolios=false,printccs=false,printacmref=false}
\usepackage[maxnames=1,minnames=1,natbib=true,
  citestyle=authoryear,bibstyle=authoryear]{biblatex}
\addbibresource{main.bib}
\end{ffcode}

\hint
Use \href{https://ctan.org/pkg/biblatex}{\ff{biblatex}} and \href{https://ctan.org/pkg/biber}{\ff{biber}}, here is \href{https://tex.stackexchange.com/a/25702/1449}{why}. Place your citations into \ff{main.bib} file. Later in the document print the bibliography with \ff{\char`\\printbibliography} command.

\section{Headings}

\hint
Capitalize all nouns and verbs in headings, \href{https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case}{here} is why and how.

\section{Typography}

\hint
Use single dash inside words, e.g.: \ff{micro-service}.
Use double ``endash'' between numbers, e.g.: \ff{pages 15-{}-28}.
Use triple ``emdash'' between words avoiding spaces, e.g.: \\
\ff{We-{}-{}-since you ask-{}-{}-disagree}.\\
Read \href{https://tex.stackexchange.com/questions/3819/dashes-vs-vs}{this}.

\section{Fonts}

\hint
Prefer \ff{\char`\\emph} over \ff{\char`\\textit}, here is \href{https://tex.stackexchange.com/a/1983/1449}{why}.

\hint
Avoid \ff{\char`\\textbf} and all other font changing commands at all cost. Here is \href{https://www.yegor256.com/2019/05/21/dont-improvise.html}{my rant} on this very problem of technical people trying to make their products look visually attractive and failing miserably.

\section{Colors}

\hint
Do not use them. Keep your documents strictly black-on-white.
Read \href{https://academia.stackexchange.com/questions/13616/are-there-good-reasons-to-avoid-using-color-in-research-papers}{more} about this.

\section{Code Snippets}

\hint
Use the \href{https://ctan.org/pkg/ffcode}{\ff{ffcode}} package,
which allows writing both code snippets and fixed-width-font
in-paragraph text blocks.

\section{Figures and Tables}

\hint
Do not force positioning in figures and tables, like
\ff{\char`\\begin\{table\}[h]}. Instead, just wrap them
in the \ff{\char`\\begin\{table\}}.

\hint
As recommended by \citet{clancy2020}, make sure
the explanation you place into \ff{\char`\\caption} is
detailed enough to let your reader understand the content without
searching the text; see how it is done in
\href{https://arxiv.org/abs/2203.07814}{this paper}.

\hint
Prefer a list over a table and a table over a graph.

\hint
Align text cells by left, center headings, and align cells with numbers by right (read \href{https://latex.org/forum/viewtopic.php?t=24435}{this discussion}); \href{https://ux.stackexchange.com/questions/24066/what-is-the-best-practice-for-data-table-cell-content-alignment}{here} is a more detailed discussion. Here is an example of a table properly formatted:
\begin{docshot}
\documentclass{article}
\usepackage[paperwidth=3in]{geometry}
\pagestyle{empty}
\usepackage{booktabs}
\usepackage{tabularx}
\begin{document}
\begin{tabularx}{\columnwidth}
  {lr>{\raggedright\arraybackslash}X}
\toprule
Name & Age & Role \\
\midrule
Jeff & 35 & The creator of the main
algorithm and the owner of the code \\
Sarah & 38 & The architect of all
microservices and the developer of
Java modules \\
\bottomrule
\end{tabularx}
\end{document}
\end{docshot}

\hint
Put all tables into the \ff{table} environment (the \ff{\char`\\caption} goes on top):
\begin{ffcode}
\begin{table}
\caption{Caption}
\label{tab:my-table}
.. content goes here
\end{table}
\end{ffcode}

\hint
Put all tables into the \ff{figure} environment (the \ff{\char`\\caption} stands at the bottom):
\begin{ffcode}
\begin{figure}
.. content goes here
\caption{The caption}
\label{fig:my-figure}
\end{figure}
\end{ffcode}

\hint
In the \ff{acmart} document class, use the |\begin{table*}| and |\begin{figure*}| (with a trailing asterisk),
in order to render it whole-page wide.

\section{Bullets}

\hint
Prefer in-paragraph itemization over a vertical one and use
the \href{https://ctan.org/pkg/paralist}{\ff{paralist}} package:
\begin{docshot}
\documentclass{article}
\usepackage[paperwidth=3in]{geometry}
\pagestyle{empty}
\usepackage{paralist}
\begin{document}
The following sources were analyzed:
\begin{inparaenum}[1)]
\item GitHub,
\item Google,
and
\item Stack Overflow.
\end{inparaenum}
\end{document}
\end{docshot}

\hint
In all itemization use \href{https://en.wikipedia.org/wiki/Serial_comma}{Oxford comma},
as in the list above before the ``and'' (provided there are more than two items).

\section{URLs}

\hint
Use the \href{https://ctan.org/pkg/href-ul}{\ff{href-ul}}
 package and then the \ff{\char`\\href} command.

\section{References}

\hint
Do not use the \ff{\char`\\ref}. Instead, use the \ff{\char`\\cref}
from the \href{https://ctan.org/pkg/cleveref}{\ff{cleveref}} package.

\section{Citations}

\hint
This code demonstrates how to use \href{https://libguides.murdoch.edu.au/APA}{APA}-style
citations with \href{https://journals.aas.org/natbib/}{\ff{natbib}} commands:
\docshotAfter{biber $2}
\begin{docshot}
\documentclass{article}
\usepackage[paperwidth=3in]{geometry}
\pagestyle{empty}
\usepackage[natbib=true,citestyle=authoryear,
  bibstyle=authoryear]{biblatex}
\addbibresource{main.bib}
\begin{document}
In \citeyear{west2004} it was already
mentioned by \citeauthor{west2004} that
object-oriented design is
declarative~\citep{west2004}. Later,
\citet{eolang2021} suggested a new
programming language in this paradigm.
\printbibliography
\end{document}
\end{docshot}

\hint
Place \ff{\~} (tilde) symbol before the \ff{\char`\\citep},
in order to avoid line breaks,
\href{https://tex.stackexchange.com/questions/41264/what-is-the-difference-in-citing-referencing-with-or-without-tilde}{see why}.

\hint
Do not use \ff{\char`\\cite}, only \ff{\char`\\citep} and \ff{\char`\\citet}.

\hint
Prefer \ff{\char`\\citet} over the \ff{\char`\\citep},
making references more obvious, as in the second sentence in the example above.

\hint
Do not type author names or reference titles directly,
only use \ff{\char`\\cite*} commands.

\hint
Remember that \href{https://www.ece.ucdavis.edu/~jowens/biberrors.html}{brackets are not words}.

\hint
Do not cite Web pages or any other URLs. However, if you need to do this,
use the following format in the \ff{.bib} file:

\begin{ffcode}
@misc{bugayenko2019blog0521,
  author = {Bugayenko, Yegor},
  title = {{Please, Don't Improvise}},
  howpublished = {\url{https://www.yegor256.com/190521.html}},
  year = {2019},
  note = {[Online; accessed 09-04-2024]}
}
\end{ffcode}

\hint
Add \href{https://ctan.org/pkg/bibcop}{bibcop} to your document,
to make sure the \ff{.bib} file is properly formatted.

\section{References}

\hint
The references in the \ff{.bib} file are usually imported from
Google Scholar or similar sources. Unfortunately, such imports
often contain typos and mistakes.
Use \href{https://github.com/yegor256/bibcop}{bibcop}
to check your \ff{.bib} file.

{\raggedright
\bibliographystyle{ACM-Reference-Format}
\bibliography{main}}

\end{document}