An Academic Workflow Cheatsheet

Introduction

There are many different considerations that go into setting up an academic workflow. Much of this will come down to matters of preference or of inertia. That is, it can be highly dependent on both what one is used to doing, and what one is comfortable with or interested in adjusting.

For many people it is good enough to stick with Microsoft Word and manual footnotes, citations, and bibliography formatting. For others, a hybrid approach that uses Microsoft's own citation manager or Zotero or Mendeley for at least part of the process of bibliography management is just fine. But for me, and I suspect for many others who find the process of formatting and reformatting things manually onerous or just begging to be automated, there are alternatives.

In this document I will try to provide a clear account of my own workflow that lists out the elements, with explanations of what I see as the value of each of them.

It may seem daunting at first, but I believe that my approach is simpler, easier, and more effective than alternatives (especially traditional LaT eX or Word solutions)!

The list is as follows:

  1. Text Editors:
  2. Markup Languages:
  3. Bibliography Management:
    • Zotero / Mendeley / MS Word's Citation Manager.
    • .bib file(s)
  4. Cheatsheets
  5. Version Management

1. Text Editors

My preferred text editor is VS Code. There are many other editors that will function more or less similarly, but VS Code has two main things going for it:

a) It's a Microsoft product with a very extensive and well-developed feature set, and, b) It has a robust developer community that has provided exellent extensions that allow for easy writing, typesetting, and customization.

On the first point, it's worth noting that VS Code allows many advanced features including remote development, which I use to work from my laptop while saving files to a desktop computer (treated like a server). It also has top-notch support for Git versioning / Github with a single click (which I will go over in Section 5).

The main thing that makes VS Code so excellent is that it has a set of extensions that make writing academic papers in Markdown extremely easy compared to, say, the default editors that come with LaT eX distributions.^[Though I will admit that there is much to be said for Overleaf as a method of writing academic papers. One problem with this approach is that it is done in the browser, and subject to all kinds of issues that arise from leaving control of the development environment up to a third-party company.]

The extensions I use are: Markdown All in One, markdownlint, vscode-pandoc, and Pandoc Citer. The first two allow very easy automatic formatting, error-checking, and code-completion for Markdown. The latter two are specifically for document conversion from Markdown to multiple other possible formats, including PDF, DocX, HTML, and ePub.

Since this method uses Pandoc under the hood, it allows for all the same customization that Pandoc does, for those who are familiar with using it for LaT eX documents. The only additional tweak I typically need to employ is to add --citeproc to the Pandoc DocX Opt String in the settings (I will explain how to do this below). This allows for proper production of LaT eX -style citations from the markdown source.

If another text editor (such as Atom or SublimeText or VIM) is preferable, I'm sure there are ways to approximate much of what I have suggested above. After all, markdown can be written anywhere, but the trick is to also allow the automatic citation shortcut to work.

Setup

Here is a brief overview of how to set up VS Code for academic writing.

... To be continued.