How to write papers#
Text quality#
There is no instruction or manual for writing great texts. However some stylistic mistakes are certainly straightforward to write down, to learn, and to implement.
A classic manual: Read and follow Strunk & White The elements of style (available at the library or online). You can check your text for some of the S&W rules using TextLint: http://textlint.lukas-renggli.ch
Avoid unnecessary words: If you can throw something away, do so. Check every single word if it is needed.
Passive voice: Search for “ed “ and “en “ in your complete draft, find which occasions correspond to passive voice and reformulate the sentences in active voice. Same goes for most modal verbs such as “can”/”may”, except for the cases when they are really necessary.
Logical connections (experimental): Within a paragraph ensure that the connection between every two sentences is clear not later than halfway through reading the second one.
Length: Every sentence should have more than three components (so no ‘subject-predicate-object’, ‘subject-characteristic-predicate’) in order to not look stupid. At the same time every sentence should have less than three clauses, or it becomes too complex to read.
Acronyms: Don’t introduce an acronym until you find that you use a >2 word combination more than 5 times in a draft, and you find you cannot think of a shorter expression.
Symbols: Once you have a complete description of what you have done, check that all the symbols are defined. It’s best to do so by making a full list of symbols that you use in the paper, and finding the definition of every single one. Also, be sure that there is no symbol collision, i.e. a symbol having two or more definitions throughout your paper.
Units: In latex, there is the siunitx package for writing units. See the discussion and use here: http://tex.stackexchange.com/questions/107818/why-use-a-package-to-typeset-units.
Panel references: According to the APS standard, figure panels should be marked with (a), (b),…, and references in the text should be the same: Fig. 4(a).
Structuring the manuscript#
When starting a manuscript it is useful to first define the structure of the text by writing one or two sentences summarizing each paragraph. It should be possible to understand the main message of the paper by just reading these bullet points.
Use the following snippet in your
.tex
file:\renewcommand{\comment}[2]{#2} % Uncomment the following line for paragraph descriptions to appear in the file. %\renewcommand{\comment}{\paragraph} % Uncomment for comments to appear in pdf TOC. \newcounter{CommentNumber} \renewcommand{\comment}[1]{\stepcounter{CommentNumber}\belowpdfbookmark{#1}{\arabic{CommentNumber}}}
and write each of the sentences with a
\comment
command. You can then output a formatted list of all the sentences with the following shell command:grep comment{ MANUSCRIPT.tex | awk -F"{|}" '{print $2, "\n"}'
Technical#
Code quality: Since it’s common practice to publish code together with the paper, it’s important to write readable, well-structured code. This starts of course with the PEP8 style rules https://www.python.org/dev/peps/pep-0008/. On top of that:
Make sure variable names in your code correspond to the symbols you use in your paper.
Usually, code can be split in functions that generate a certain system, and functions that do computations with that system. It might help to separate these two types and store them in separate python modules. Results can then be generated in short notebooks where you import these python modules.
Raise exceptions in the code when appropriate.
Provide up-to-date docstrings in the main functions to make clear what a function does, what it takes as input and what it gives as output.
Code running: Make sure, before submitting your code to arXiv, that it works as expected, is bug-free, and generates results corresponding to the figures in your paper.
Makefile: Writing a paper involves a lot of back-and-forth modifications to the text and figures. That’s why it pays off to keep the text under version control and automate the process of building the paper using a ‘’Makefile’’. The idea is that running ‘’make’’ from the repository should just create the ready manuscript. For this you need to make every step automatic, luckily it’s very easy. See for example the Makefile in the ‘’electrostatics_paper’’ repo. There, e.g. “make pdf” will just generate the paper pdf, “make code” will make a directory with all the code files and “make arxiv” will both generate the paper pdf and code directory, and store everything in .zip format. The only trickier thing is adding a manually draw panel or inset to a matplotlib figure. For this you can use the svg_utils package (see http://neuroscience.telenczuk.pl/?p=331 for details), or you can use holoviews.
Bibliography#
(Anton’s recipe)
I’ve found an easy way to make a consistent and complete .bib file. Here it is:
Get zotero
Create a temporary zotero collection
For each of the papers you need go to the journal page and click on the zotero import link
Export the references from Zotero to bibtex (check the checkbox ‘use journal abbreviation’)
This ensures that all the references are complete and have the same format. It still requires more work: arxiv references can be made in several different ways, for example you can set the journal field to read journal = {{arXiv}:1908.123456 [cond-mat]}
.
Standalone installer: If your OS doesn’t have an appropriate package you can find an installer of zotero standalone version on github.
Better BibTex: It is a Zotero extension that adds a few extra features for exporting bibliography to BibTex format. The installation instruction can be found here (make sure you get extension for appropriate version of Zotero). Features I found most useful are:
automated export to
.bib
file when bibliography changes (can be turned on/off or triggered on demand)references can be tagged with
#LaTeX
to avoid escaping of latex characters in titles/abstractspossibility to exclude certain fields from export, like notes or file location on your hdd