Suggestions for improving scientific writings and the use of LaTeX

In this page, I humbly share a summary of the things that I frequently report to my co-authors. Many of those things could be called errors, while some others may be considered as a matter of taste.

Some frequent LaTeX mistakes

Use of non-breaking spaces

Add an non-breaking space (~) in front of most \cite{…}, \page{…}, etc. For example:

Warren~\cite{Warren1965} was the first to…

See figure~\ref{fig:test} on page~\pageref{fig:test}.

Reference: https://en.wikibooks.org/wiki/LaTeX/Labels_and_Cross-referencing

Compatibility with Version Control Systems

Write each sentence on a single text line

  • It helps to keep track of word changes across revisions.
  • A long text line probably indicates that the sentence is too long and needs to be written differently. The practice of using one text line for each sentence helps identifying text structures that may need some simplification.

Don't use your editor's reformatting tools

Or this may introduce unwanted changes in the versioning history.

For example, considering this short example:

This section presents the existing works that investigate approaches
to evaluate...

… Adding the word new to the sentence, combined with editor formatting, modifies two text lines where a single word was actually modified in the text.

This section presents the existing works that investigate new
approaches to evaluate...

The addition of one word, if combined with text reformatting, let's a VCS (e.g., git) report that two text lines were modified:

$ git diff
- This section presents the existing works that investigate approaches
- to evaluate...
+ This section presents the existing works that investigate new
+ approaches to evaluate...

If the sentence is kept in one single text line, git diff correcly reports a single change:

- This section presents the existing works that investigate approaches to evaluate...
+ This section presents the existing works that investigate new approaches to evaluate...

Nota: git diff provides an option to highlight changed words instead of changed lines. The output is more readable with color output (not illustrated here). However, I suggest not to rely on this option of git, because all your co-authors may not be aware of this option, and they will probably not use the same git client.

$ git diff --word-diff
This section presents the existing works that investigate {+new+} approaches to evaluate...

Typography

in French

For the French typography, read the Lexique des règles typographiques en usage à l'Imprimerie nationale.

Non-breaking spaces (~ in LaTeX) are required before many punctuations, e.g., ?, !, :, ;, » (hence, also after «). For example, you would write in LaTeX: «~Salut, la compagnie~!~»

The babel package, if correctly configured, is usually able to manage the use of non-breaking spaces automatically for you, but YMMV.

For LaTeX black-belts: \, inserts a thinspace, which is also non-breaking. Mostly used for math notations. LaTeX supports a plethora of different white spaces.

in English

For the English typography and many other topics related to writing, read the Little, Brown Handbook.

English does not use non-breaking spaces before punctuation marks. For example, you would write in LaTeX: "Hello, World!".

In English, the white space following the full stop at the end of a sentence is longer than other spaces between words. LaTeX automatically takes care of that for you. Other spaces after a dot usually require a normal space, which is annotated \ =. For example: =e.g.\  (even though some manuals of style require the use of a comma after "e.g." or "i.e.".

Writing style

There are many good resources about writing style. My writings are probably not exemplary with regards to writing style, but I suggest here a few things that are not given enough care.

I recommend these two excellent books, frequently re-edited and revised:

Fowler, H. R., Aaron, J. E., & McArthur, M. (1992). The little, brown handbook. Pearson.

The Chicago Manual of Style, 17th edition (2017). University of Chicago Press.

Don’t use adverbs

Most of the time, adverbs do not contain useful information, and can be removed without changing the meaning of the text. In many cases, it is better is to think about a more expressive verb, or to write differently the sentence.

If you really need an adverb, think about it twice.

Adjectives are likely to receive the same treatment.

Jargon consistency

Check the consistent use of every term in the paper. You should use only one word for each use of the same meaning in the whole document. If you need two ore more words, make it clear to the reader that they mean different things, albeit close or related.

Use a grammar checker

Most LaTeX editors do not support grammar checking. Or maybe, most users of LaTeX editors do not use grammar checking. I don't know.

Use a spell checker

Period.