An approach to paper writing

This is a description of how I strongly prefer to manage the paper writing process, and a rationale. If you are a student I am advising, this is the default (but not 100% required method) for how we'll work on papers.

Version Control

git
source-of-truth repository on github/gitlab/bitbucket
rebase commits before push
use meaningful commit messages
keep commits focused

Paper Organization

Paper text goes in text/
Figures go in figures/
Bibliographies go in bibs/
One LaTeX file per-section
Files have 1-2 word names
Use the skeleton

Paper Commits

A good paper edit commit has a specific job and changes only 1-2 files of the paper, with the exception of spelling/grammar passes.
Commiting/adding large images (e.g. temporary diagrams) will make the repo and pdf difficult to handle. If you are adding a photo of a temp diagram, downscale it first. This can be done with many tools, e.g. with imagemagick's 'convert':
convert INPUT_FILE -resize 400x300 OUTPUT_FILE

Commit messages should make it relatively clear what the objective of the commit was and the list of changed files should make sense given that objective. Unlike (good) code commits, it is OK if a paper edit commit message might not make much sense a few months after being written.

Here are some commit examples from the Augury project:


"adds s5b rought draft, ports interesting oddities subsect into s5b removing subsubsects, adds some comments"
edits: reversing.tex

"address comments in result of aop v baseline existence experiment"
edits: existence.tex

"added backref to discuss the XABC pattern in threatmodel"
edits: existence.tex
       threatmodel.tex

"Spell checks"
edits: DMPs.tex
       abstract.tex
       background.tex
       existence.tex
       introduction.tex

Style notes

LaTeX and git diffing works best when each sentence goes on its own line. I encourage turning on visual line-wrapping in your editor of choice, and turning on some sort of auto-reflow for one-sentence-per-line. If you use emacs, I have a pile of bad elisp for this behavior.

Why?

I prefer this methodolgy for four reasons:

It makes it such that at a glance of git history, you can see who has edited what recently in the paper, and why they did it.
It encourages focusing on the text you are writing, not the rendered PDF.
It makes diffing across paper versions simpler.
It means that Overleaf/etc going down on deadlines is not a concern.

A note on protocol for collaboration

A 'downside' (or maybe really a tradeoff) of this methodology is that it may require taking "a lock" (asking for no one else to edit) on a paper section during writing. This will need to be communicated to your co-authors via email or slack. Don't take locks for more than 24 hours if you can.

Bonus features

Git commits for paper development make lots of retrospective analysis easier! For example, you can make an entirely pointless video of your paper's development over time with a script.