Miskatonic University Press

Managing the draft of a paper as if it were source code


A couple of months ago I submitted a paper to the Code4Lib Journal called "On Dentographs, A New Method of Visualizing Library Collections." The editors were interested in it and one of them, Gabriel Farrell (@g5f), was assigned to see the paper through the process and work with me on editing and improving the draft.

The last paper I did, Sarah Coysh and I started writing it in Google Docs and then moved it down to Microsoft Word and shared the file on Dropbox. We submitted the Word file and then worked with the editor using the comments and track changes features in Word.

That all worked well for that situation, but on my own I avoid Word as much as I can, and anyways it just doesn't feel right to do something Code4Lib-related in a proprietary system. Because a C4LJ paper ends up being HTML, I decided to write it in Markdown. Markdown is plain text, with very limited and unobtrusive markup, nice and simple. It keeps all the cruft out of the way and is mostly meant for conversion into HTML but can also be turned into other formats. Emacs's Markdown and outline modes help. I made a little Makefile so that with one command I could regenerate a fresh HTML version of the paper and publish it to my site if I wanted.

After Gabriel got assigned, he asked if I was interested in working together by sharing the draft files through a distributed version control system. He'd done it before and said it worked well. I said sure.

The result: a GitHub repository of the draft of On Dentographs.

dentograph-paper.markdown is a plain text file (GitHub renders it as HTML; click raw to see how it really looks) that is, in effect, the source code of the paper. Gabriel has forked the project and when he has a change to make he will edit his copy of the file, commit it to his repository, and then send the suggested changes to me in a "pull request." He's submitting patches to my source text, same as if we were working on a software project together he would submit source code patches. I get notified and can accept, modify or reject the patches.

I'd never heard of this being done (perhaps it's not uncommon?) but I think it will work very well. If you're interested, you can watch the project and see how the editing goes — submit a patch of your own if you want, and I'll consider it. The final draft will be in by the end of the month and if they accept it it'll be online in final form at the end of January.

P.S. I have these lines in my .emacs so that .markdown files work how I want:

;; markdown-mode
(autoload 'markdown-mode "markdown-mode.el"
  "Major mode for editing Markdown files" t)
(setq auto-mode-alist
  (cons '("\\.markdown" . markdown-mode) auto-mode-alist))
(add-hook 'markdown-mode-hook 'turn-on-outline-minor-mode)
(add-hook 'markdown-mode-hook 'turn-on-visual-line-mode)