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:

  1. Get zotero

  2. Create a temporary zotero collection

  3. For each of the papers you need go to the journal page and click on the zotero import link

  4. 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/abstracts

    • possibility to exclude certain fields from export, like notes or file location on your hdd

Authorship#

The interpretation of the author order depends on the community, and therefore should match the community expectations.

Within our community the authors closer to the end of the list are expected to be more senior, to be involved with the project more in the advisory role, and the last author will typically be the one who defined the project unless that’s the first author.

The first authors are typically more junior, and typically will do more of the work in implementing the code, performing calculations, and running simulations.