The Living Thing / Notebooks : Academic writing workflow

Beautiful typesetting with LaTeX

“Documenting my academic writing workflow and how to improve it”, or, “How I learned to stop worrying and love text files”.

Writing for the internet

Blogs etc.

This blog, and virtually all my notes, are in plain text files on my computer, published online as plain html files. (Some are in jupyter notebooks.) It’s an informal open notebook.

I had to jump through some hoops to make this work, because I need mathematical markup support and basic citation management. Vanilla, non-academic plain text blogging is simpler. But even this academic stuff is not complicated.

Why bother?

Open notebook science is a thing. It improves reproducibility of research. Personally speaking, it keeps me more rigorous, knowing that the public can see what I am doing, and which half-cocked opinions I am holding. It encourages people to contact me about my ideas.

Further, having a bunch of plain text files is the most simple, convenient and reliable way of taking notes. I’d do it this way even if it weren’t going to be online.

If you want more in-depth justifications for open notebooks, see Caleb McDaniel or Ben Marwick’s slide deck.

Other examples of online notebooks

Technical details

I publish notes online using Pelican. I see plain text files; you see fancy online HTML. The HTML is automatically served by github pages, which is fast and free. The citations are handled through Zotero. This is a work in progress. This workflow is OK, but I’m experimenting with some alternate preview tools such as marked, and restview.

Nafiul Islam gives some clever shortcuts on getting live preview using livereload.

But for now I mostly edit the text using Atom, and just GO. The process looks like this:

Screencap of my text editor

On hosting choice

In the past, I used many online services to handle my information; but I’ve been burned too many times by these businesses going under, or being too inflexible to evolve with my workflow, or relying on me being constantly online, which is not a given in many parts of the world I want to work. Waste of time, loss of data. (So long, delicious.com, citeulike.org, evernote, google docs…) Fuck that.

The only online services I use these days are:

  • Zotero, which avoids the bulk of the above criticisms by the fact that it’s open-source, works great offline, is backed by a presumably comparatively benevolent university, and handles only information that I wish to share.
  • github isn’t open-source, but the underlying technology it facilitates, git, is very open-source, and the website itself is replaceable for my purposes, so I’m happy to benefit from the commercial sheen they buff onto to the bare pipes.

I send both of those two latter projects money. On the other other hand, I entrust them with only minimally confidential data.

On software choice

There are lots of tools to do this. As to why I chose Pelican over Jekyll: I am more fluent in Python than Ruby As to why I chose Pelican over Nikola: I can’t remember. When I set this thing up, there was some feature I needed from Nikola that it was missing, I guess? They seem to have converged to being the same software with different code now anyway. There are a few hundred other static site generators too, if I want to burn time searching. The other well-supported ones for academics seem to be jekyll-scholar, and the Sphinx extension Ablog is probably effective.

One might also dilate on one’s themes through sphinxtr, the “Sphinx Thesis Resource”, which is similar but thesis-oriented and better suited to longer passages.

Writing papers

Writing papers, especially collaboratively, is a whole other story; you need better media management and citations etc. And you need to work with collaborators of different technical expertise levels, and various quirky workflows.

Here are some tools that attempt to ease that:

There are some extra questions if you want to integrate computation etc into your workflow. Then you might want to try to use a scientific notebook such as jupyter, knitr etc.

See also text editors, LaTeX, citation management, scientific computation workflow, plain text blogging.

To read