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

Paper Organization

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

"Spell checks"
edits: DMPs.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.


I prefer this methodolgy for four reasons:

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.