During writing and reviewing, I compiled the following list of style "anti-patterns" and hints:
- Woolly language: text that can be removed without changing the meaning of a sentence.
For instance: while being either inside or outside, I like to eat ice cream. Better: I like to eat ice cream.
- Woolly formalisms: avoid timestamps and identifiers wherever possible.
It is not programming, it is formal writing.
For instance: an event log is a set of events; each event has a unique timestamp and a trace identifier; a trace is a sequence of events, ordered by timestamp, with the same trace identifier.
Better: an event log is a collection of traces, which are sequences of events.
- Term switching/avoid synonyms: if two terms refer to the same thing, then the terms should be the same.
It makes the text boring, true, but also much easier to understand.
For instance: I was sitting on the couch when suddenly our cat joined me on the sofa. Better: I was sitting on the couch when suddenly our cat joined me on the couch.
- Figure misplacement (1): \vspace and \hspace: do not fight with Latex's layout system; you'll not win.
Use the appropriate length adjustments to save space, such as textfloatsep.
- Figure misplacement (2): \begin{figure}[hbtpH!]: if you do not want something to float, then do not make it a float.
For best spacing, use [t] or [b], but only at the end of the writing process, just before submission.
- Font inflation: use $a$ for variables, $A$ for sets and tuples, and $\mathcal{A}$ for sets of sets.
Use $f$ for functions.
If running out of letters, use Greek letters.
Use \texttt{a} for constants.
Do not introduce symbols for universes: if it is necessary to explicitly formally bound a variable (often, this can be done in text), do it from a specific set, not from a universe.
- Overemphasis: indicate emphasis with \emph, as this allows the template to determine how emphasis is created. That is, do not use \textbf, \textit or \textsc.
Emphasise the following:
- In a definition environment, emphasise the concept(s) you are defining.
- In an in-line definition, emphasise the concept(s) you are definining.
- In the introduction, you may emphasise the key distinguishing factor.
- If an abbreviation is too similar to a normal word, then \textsc the abbreviation.
Do not emphasise anything else.
If you feel the need the emphasise a certain phrase, then rewrite the parts around the phrase.
In a well-written text, emphasis distracts and is counterproductive.
- Overcapitalisation: capitals draw attention and should be used sparingly.
Capitalise the following:
- In top-level section headers, capitalise the first word and every word that is not a small word (on, in, the, etc.);
- Names of particular algorithms, formalisms, people, etc.: 'Business Process Management and Notation', `Petri net', `Heuristics Miner';
- Abbreviations: stochastic labelled Petri net (SLPN);
- References: `Section 4.1' and `Figure 5'.
Do not capitalise the following:
- Small words, such as on, in, the, etc.;
- Lower-level section headers: (only capitalise the first words and proper names);
- Names of research fields or generic concepts: 'business process management', `directly follows graph', `Petri net';
- After a colon (:), unless a completely new sentence starts;
- Multiple references: `sections 4, 5 and 6'.
- Every float (table/figure/algorithm) must have a caption and be referred to in the text. The caption should end in a period, and be descriptive but short and concise.
- Avoid lines within tables at all cost (except between the header and the body). Use the booktabs package to add \toprule, \midrule and \bottomrule.
Use white space to separate groups of columns or rows visually.
Align every number to the right, and everything else to the left.
- Data, information, semantics and behaviour are only used in a singular form: `some data is obtained', `multiple types of behaviour'.
- I prefer English (sometimes also called British English), but ensure the dialect of English is consistent.
Commas serve to assist readers in understanding the sentence structure (unlike in German, where they are part of the grammar).
Use them sparingly; avoid Oxford commas, unless they help avoid confusion.
- Keep Latex source code organised:
- Indent like you would program code. This helps to keep track of environments and sections.
- Start every sentence on a new line. Collaborators and future you will be grateful, and diff tools will work better.