Tech and Math For Lawyers

My academic writing toolkit/workflow

This one is for academics rather than practitioners, though some of the details are applicable to practitioners as well. I have an unusual and complicated academic writing workflow/toolkit, but one that might be of use to some other people, so I thought I’d share it here. This is a work in progress document; I’ve promised to share my toolkit with a couple people, so, as those people say to me “hey, this makes no sense,” I’ll probably edit to clarify.

Here are the considerations, in rough order of priority, that drive me:

A. I like to have lots and lots of backups. I’m incredibly paranoid about losing work.

B. I utterly loathe Microsoft Word. I won’t use it if it can be helped at all. Yet I recognize that many people that publish things I write need Word format, so I need to do something that converts to Word fairly readily. Subconsiderations:

1. I want something that doesn’t crash or hang all the time, unlike Word. (It’s utterly mind-blowing how badly Word performs. I have a brand new souped up 16-inch Macbook Pro with an i9 and 32 gigs of ram. Word still takes forever to start. It takes longer to start than XCODE, which, for those of you who program, you’re probably screaming in horror at the very idea.)

2. If I want to do something weird or automated with my content, I want to be able to do so. My writing needs to be scriptable—-I need to be able to read my writing into an ordinary programming language as a string, run code on it, and spit it back out again as a string. This requires a plain text format.

3. I also want something that doesn’t impose involuntary formatting on me. Word “features” like styled paste, auto-conversion of URLS to links, bizarre dictatorial bullet point numbering, etc. etc. etc. are anathema to me.

4. Most of the major alternatives to word (OpenOffice, Google Docs, Pages) are crap.

C. I also hate manually formatting my citations.

D. I like being able to relatively seamlessly switch between writing on my MacBook and on my iPad.

E. I want to use git for version control so that I can recover prior versions if something gets horribly screwed up.

So my workflow has the following elements:

1. I write everything in markdown. Markdown, for those who aren’t familiar, is a plain text format with very lightweight markup for things like bold/italics, links, and the like. It’s readily convertible to MSWord format, as well as PDF (if you’ve installed LaTeX), HTML, and all kinds of more arcane things—-it’s very commonly used by programmers and bloggers, and I think it’s by far the best way to write initial drafts. There are different flavors of Markdown (for reasons to be described below, I use the Pandoc version), but the basics are very simple. For people who are interested in Markdown, I wrote a tutorial on how to work with Markdown here. Typically, for longer works (big articles, books) or multi-stage projects, I’ll have multiple markdown files with different logically separated portions of text, plus files for notes, paragraphs that need to be discarded or moved to a better home, etc. etc.

2. On the Mac, I do most of my markdown writing in Sublime Text, which is a totally bulletproof programmer’s text editor. I use Sublime Text pretty much only for editing markdown or plain text prose—-when I write code, I usually use emacs or vim—-so I don’t have to muck around with complicated file-type-specific settings. There are fine alternatives for editing plain text, like Atom, BBEdit (Mac-only), and Notepad++ (Windows-only). But I like Sublime Text over those other alternatives because (a) it’s extremely fast, stable, and lightweight (basically the opposite of Word), and (b) it has a plug-in system based in Python, which is one of my preferred programming languages—-so it’s very easy for me to directly program my editor. The major downside is that it is expensive, although the developer lets you use it without paying if you can put up with periodic scolding popups.

3. Everything is saved to a git repository which gets to be in a private repo on GitHub. That’s a lot of technobabble, let me break that down some. Git is a version control system—-basically, it lets you say “ok, here’s a point where I want to declare that this is a version of my document” (called a “commit”), and then it saves all your commits, so any time you want, you can go back to a previously declared version of the document, see the differences between the current version and that version, etc. This system was designed for programmers, so it really only works reasonably well with plain-text formatted writing. Github is an online service that hosts git repositories—-basically, a repository is a project, and you can (manually) synchronize the repository up to the cloud and then access it on another device. For more, this introductory guide to git and GitHub is a good start.

4. When I want to work on my iPad (which is my main mobile writing station—-an 11-inch ipad pro with the keyboard folio), I use Working Copy, a git client for iOS that comes with its own built-in text editor that’s actually pretty good. I basically just pull (sync) the repository from Github, write in that app, and then sync it back up, then do the same on my computer when I’m writing there.

5. I save all my references in Zotero; the only plug-in I really rely on for Zotero is Better BiBtex. Zotero is a reference manager that allows you to do things like click a browser plug-in button to save a source directly to one’s library from something like JSTOR; I’ve tried them all, and Zotero is the best. Better BibTex is a plugin for Zotero that just smoothes out some of the rough edges in a text-based workflow. With Better Bibtex installed, you can automatically export all your citations to a reference file saved in a format that Pandoc can read (see below; I recommend using CSL JSON format). Then, when you write, you add a citation to a document by putting a specially formatted “citation key” in your markdown file. (For example, a current project of mine contains the text “Manifestly, much of the motivation for Republican legislators to enact this bill was a desire to prevent the Klan from suppressing enough Black voters in the South to forcibly elect Democrats—-i.e., to protect their partisan interests [@treleaseWhiteTerrorKu1995, 388-9].” The bit in the brackets is a citation: BetterBibtex decided that the Trelease book would have the key “treleaseWhiteTerrorKu1995,” and I copied that from Zotero to my markdown file. In the next step, that automatically turns into a real citation.)

6. Finally, the thing that ties it all together: I use Pandoc to convert my writing files to a format that won’t make other people angry. Pandoc is a commandline tool that can take a markdown file (or lots of other formats) and convert into PDF (via LaTeX, which is a whole ‘nother ball of wax, but with Pandoc you don’t have to touch it, though you do have to install it) or Word formats (or, again, lots of others too). It can also take the citation file produced by Zotero and Better Bibtex and fill in the citations in a format of your choice. So, you can feed your markdown file and your citation file into Pandoc and get out a PDF with nicely formatted citations, and, incidentally, nicely formatted text, without ever having touched Microsoft Word. Which is basically Nirvana for me.

I tend to go through a process using these tools over and over. I’ll write some markdown files. When I think I have a draft of something, I’ll convert it to PDF and open it up on my iPad for editing (using iAnotate and the apple pencil to essentially simulate the experience of printing out a draft and marking it up). Then I’ll go back to my markdown file again and put in my edits. And so on, and so forth.

For more complicated, larger, projects (long articles, books), I’ll often involve Scrivener into this process. I don’t write in Scrivener (though lots of people do, and seem to do so happily). Rather, I find that every large project tends to get into a messy, tangled, downright gnarly state where I have like a dozen markdown files with different parts of the text, and I’m no longer clear in my own head on what the best organization is. When that happens to me, I’ll start a new Scrivener project, import all the writing files directly in there, and then use the visual splitting, merging, and reorganization functions that Scrivener is famous for to reorganize the text as a whole. Then I’ll dump the whole thing right back out into one big markdown file, and go right back to Sublime Text to keep working from there. I find that Scrivener is kind of a safety blanket for me: sometimes when I want to write, I want to write, and spending a bunch of time thinking about organization/how exactly what I’m writing fits into the broader system of the project can get in the way and waste productive putting-words-on-paper time. Having the confidence that I have a really good tool to go back and fix all my organization problems frees me to just write and worry about where the writing goes later.

This system isn’t perfect. It has the following rough edges:

• Zotero doesn’t really work on iPad. There’s a zotero client for iOS called Papership, but it’s unreliable and has crap features; I haven’t figured out any way to actually add sources to my library from within it or even get Better Bibtex citations out. Don’t waste your money. There’s also a zotero webapp, but I can barely get it to do anything on mobile Safari; I don’t know whether this is because of content blockers or just because it sucks, but it’s almost totally unusable. What this means is that when I want to cite something while writing on iPad, I typically end up putting an inline note to cite it the next time I’m on the computer; when I want to add a source to my Zotero library from iPad I usually just dump it into a designated dropbox folder, again, to handle the next time I’m in front of the computer. This sucks, but every other alternative is worse; one day I want to write my own damn Zotero client for iOS to do it all (but heaven only knows where the time for that would come from).

• Being git-first means that I don’t get automatic synchronization, like I would if I stored my work in an iCloud or a Dropbox folder (not OneDrive or Google Drive. Never OneDrive or Google Grive. Neither of those works reliably. Gdrive is at least semi reliable. As for OneDrive, I’d propose that every hard drive containing any of its source code should be set on fire and then launched into space, except judging by Microsoft’s record for doing harm to the world it would turn out that aliens would discover it, recover the code, and be so horrified by what they see that they’d exterminate humanity—-and really, that would be nothing less than we deserve for buying Microsoft products). I have to remember to manually pull every time I switch devices, and push every time I’m done with a session of working (as well as periodically while working in case something crashes). This is annoying. In principle, I could automate the macos side of this, though it might be a bit complicated to get the timing of automated push/pulls right. But I can put up with manual; with practice I’ve gotten pretty good at remembering to do it, and it’s not all that hard to fix merge conflicts if I screw something up. Git is reputed to not play nicely with Dropbox, so I can’t just store my git repository in a Dropbox folder (although I do have some jury-rigged tools to back my writing up to them.)

• My workflow only works until someone else touches a document. Once I submit to a publisher, or send a draft to a co-author when I use one, it inevitably has to be in MS Word, and then I’m back in the hellpit. Oh well.

More technical details of how I set everything up forthcoming. In the meantime, see:

1. I’ve created a github repository with a sample markdown document and citation file and instructions on how to build it.

2. Kieran Healy uses many (though not all) of the same tools I do, and has dived into much more detail on them.

Why and how to use markdown instead of (or in addition to) Word

Markdown is a plain text formatting language. It allows you, as the cool kids say, to separate content and the semantic properties of content (i.e., which bits of text are what—which bits are footnotes, which bits are quotes, which bits are headings) from the style of that content (which bits are italic, how much paragraphs are indented by, what font you’re using, etc.).

In other words: you know how whenever you write a document in Word, you get into a nightmarish rabbit hole of things like trying to convince Word when to start and stop numbering a list? Or how you can copy and paste some text in from somewhere else, and sometimes it includes the formatting, and sometimes it doesn’t? (And “paste and match formatting” seems to do something entirely random.) Well, if you just write the text in one place, and then apply styling after the fact, you don’t need to worry about that at all!

Here’s an example of a simple Markdown document.

# My Amazing Heading 

Here I am.  Writing a document.  For the following reasons: 

1.  Because I want to.

2.  Because I said so. 

3.  Shut up.

Now I'm going to write a paragraph.  Look at me, paragraph. 

This paragraph [has a link](https://google.com) in it.  Neat-o. 

You can write this with any ordinary plain text editor (like Textedit on a Mac or Notepad on a Windows machine), and then you can use a program like Pandoc (we’ll cover this below) to convert it into a Microsoft Word document. The numbered lists will be correctly formatted, without you having to fight with them. The link will work right. Every paragraph will be consistently formatted. And, best of all, you won’t have had to click sub-sub-sub menus or figure out what “ribbon” some obscure command is on. And, do you see how quickly your text editor started? And how your text editor, unlike Word, didn’t crash when you gave it a big document?

Not only that, but you might not need to touch Microsoft Word at all. You can also convert a Markdown file directly to PDF, or to a HTML page for display on the web (and to lots of other formats too).

Moreover, when you’re working in plain text, you open up lots of other superpowers. For example: Microsoft Word track changes is terrible; it makes things super-slow and, when you’re doing a lot of changes, makes them almost totally unreadable. (Law professors who have gotten thousands of tiny changes back from Law Review editors: can I get a ‘hell yeah’?) But if you’re working in plain text, you can use a version control tool called Git to track changes instead; it’s vastly more powerful, and, once you learn it, vastly easier to use on a day-to-day basis. (Git is a subject for a future article on this site.) If you’re working with really large documents, you can use programming languages and advanced, powerful, text editors to do sophisticated search and replace functions that Microsoft can’t handle. The same goes for other kinds of added functionality: lots of things that you can do in a slow and crash-prone way in Word, like insert citations with a citation manager, can be done in a more fast and reliable way using text-based tools.

There’s a little bit of a learning curve, but once you get through it, I think you’ll see that it’s worthwhile!

How to use Markdown

There are a few things you need to have on your computer in order to use Markdown.

A good text editor

You shouldn’t try to use Microsoft Word to edit Markdown. First of all, that would totally defeat the purpose (we’re trying to avoid that terrible program, remember?) Second, Word isn’t designed to produce plain text files. You should use a plain text editor.

As I said, you already have one on your computer: Windows users have Notepad, Mac users have Textedit. (If you use Linux, you don’t need this tutorial.) But in all honesty, those are kind of weaksauce text editors. Here are my recommendations.

If you, like me, are deeply embedded in the Apple ecosystem, just get Byword. It’s designed for Markdown, so it can do things like preview formatting. It syncs over iCloud between Mac and iOS devices. It’s very cheap. It’s very simple. I use it for all my basic writing, like letters and such. Some people swear by Ulysses, but it’s vastly more expensive with an obnoxious subscription pricing model, so I won’t recommend it or use it.

For more demanding uses/if you want an editor that can be extended with code, I recommend one of the following two applications, which are both available for Windows and Mac:

• Atom. Pros: free, scriptable in Javascript. Cons: can be a bit of a battery drain and resource hog (though probably not as bad as Microsoft Word).

• Sublime Text. Pros: fast, lightweight, scriptable in Python (way better than JavaScript), just a beautifully designed piece of software—there are cults of people who love it. Cons: A bit expensive ($80), although if you’re willing to tolerate nag messages you can use for free.

On Mac there is also BBEdit, which is fine. There are also dedicated Markdown editors for both platforms; like I said, I like Byword for Mac; for Windows I’m not sure what’s best.

Worth an honorable mention is Scrivener which is a multi-platform application that is beloved by many writers. It’s a kind of complicated program that allows you to break up a document into chunks and reorganize them, among many other features. It can handle Markdown input and output with a little bit of persuasion, though it’s not really a plain-text editor at heart. It’s mostly useful as an intermediate writing stage to reorganize long documents; I will often just import a bunch of sections of a long article as individual Markdown files, organize them in Scrivener, and then dump them back out as one big Markdown file for further revision.

Regardless of what platform you’re on, you’ll want to save markdown files with the extension md like myfile.md. This will help your preferred text editor know that you’re working with a Markdown file, and hence show you things like formatting previews and markup highlighting to make it easier to see what you’re doing.

Pandoc and LaTeX

Pandoc is a program that allows you to convert Markdown files to numerous other formats. (It has many other superpowers as well, but this is the key use.)

To use it, you need to get comfortable with your command line. (For Mac, this is the Terminal application under Utilities, although once you get happy with using the commandline you’ll probably want to upgrade to iTerm2. I’m not sure how to get at it in Windows, but Google will help.) Learning how to use the command line is the subject of a different tutorial, yet to be written, but here I’ll assume you know how, or can google your way through it.

To install Pandoc, you can download and run the relevant installer for your OS. If you’re using a package manager you’ll see instructions on how to do that from this page too (if you don’t use a package manager, don’t worry about it).

In order to make nicely formatted PDFs, you should also install a program called LaTeX, which is the gold standard of typesetting software. It’s a gigantic download (multiple gigs). For Mac, you can use MacTeX; for Windows use MiKTeX. I recommend just using the full, gigantic, version of the install so that you don’t ever have to worry about not having something that you turn out to need.

Pandoc and LaTeX are both free.

Using your shiny new software tools

Suppose you’ve written a Markdown file called myfile.md. Navigate, in the command line, to the folder it’s in and type:

pandoc myfile.md -s -o myfile.docx

Pandoc will convert your Markdown file to a properly formatted Word file.

You can also do pandoc myfile.md -s -o myfile.pdf to get a PDF file, and the same with myfile.html at the end to get a web page.

That’s really it! There are lots of other options, and I really encourage you to read Pandoc’s documentation, but this is the basic process.

For further assistance, see Pandoc’s Getting Started page, which also includes a basic command line tutorial.

Writing Markdown

Markdown is a very simple format. This web page describes the basic version of the format and how it gets converted to HTML tags (the original purpose for which it was designed).

One thing you’ll notice is that Markdown as originally specified doesn’t give you a lot of features. There’s no way to add tables, for example, or footnotes, or even nested lists. Fortunately, there are a variety of extended versions of Markdown floating around. I use Pandoc’s own version of Markdown, which is much more complex than the original but also much more powerful; you can just use that in a Markdown file in place of original Markdown and Pandoc will seamlessly handle it. Pandoc’s Markdown gives you nested lists, footnotes, tables, smallcaps (always nice for law review articles) and numerous other fancy things. But you should start with reading the original description of Markdown; it might be enough for you.

Markdown with Word

Another piece of the secret sauce for efficient document generation is to use Markdown in conjunction with Word. Pandoc’s built-in Word template uses styles to carry out all its formatting—just like everyone keeps telling you you’re supposed to be doing. The only difference is that adding styles in a Markdown document is lots faster easier than adding them in a Word document—if you want something to be an outline, you just have to put the little dash in, if you want something to be a block quote you just have to put a > at the start of the paragraph, etc.

Then, when you make your Word document, you already have styles defined for all the different semantic elements of your content—Microsoft Word already knows what chunks of text are outline items, what chunks of text are blockquotes, what chunks of text are footnotes, and so forth. So all you need to do is edit the styles to have them look the way you want them to look, for example, making the blockquote text indented rather than italicized. Then Word will be kind enough (assuming you know the correct clickey-clack menu incantations) to automatically change how everything else with that style looks.

This is by far the easiest way to get all the advantages of Markdown, while still having granular control over the look of your document, and without having to create or install custom templates.

Toward the future!

One very useful thing to have for lawyers would be LaTeX and Word templates for a variety of common legal documents. For example, we could build templates for the formats required for filings in various courts, so that a final document PDF could be created without ever having to touch a Microsoft product. I will happy accept contributions for any such templates on this site; I may also try to write some myself.

In the absence of this, it’s probably still necessary for the time being to use the Markdown -> Word workflow I described above for documents with interesting formatting. However, for simple documents, such as internal memos, or to generate draft documents to be worked up by support staff, Markdown with Pandoc on its own should be sufficient.

Addendum: a thread reproduced from Twitter.

In case you need some more convincing, here are my ten theses for why a Markdown/Pandoc-based workflow is better than anything involving Word (largely repetitive of the above, but in a nice list for easy propaganda distribution):

1. Performance. Even on my fast machines, word takes forever to start up and occasionally lags. A lightweight text editor doesn’t.

2. I can keep track of changes by putting documents in a git repository, as opposed to the slow unreadable mess of Word track changes.

3. I can easily edit on other devices, even an iPhone.

4. Pandoc’s word template is fine formatting for most of my uses; LaTeX, of course, is actually good formatting unlike anything Word can produce (which is why people who produce serious documents with actual desktop publishing appearance demands do not ever use Word—they use LaTeX if they’re math/science people, and Adobe InDesign if they’re artsy/marketing people).

5. As you add special features to Word documents, like citations linked in with Zotero, it gets even more slow and crash-prone. With Markdown and Pandoc, this is plain text and you can just compile with a Zotero-generated BibTex file.

6. Same goes for math when I use it. In Markdown you can use LaTeX math. I once lost an entire chapter’s worth of equations in copy editing because of MS Word bugs/version incompatability.

7. For putting together or tweaking large documents, doing them in plain text makes it much easier to automate things, like regular expression replacements.

8. Markdown produces many other formats. For example, if I decide I want an HTML page for my document, it’s easy. (And markdown processors, unlike word, do not produce shit HTML.)

9. I don’t have to use lightweight text editors like Byword. If I need really fancy stuff, I can use text editors with insane amounts of power, like Vim or Emacs.

10. Numbering and bullet points are actually predictable with Markdown syntax. It’s not random shit where Word guesses as to whether you want a bullet and you have to sacrifice a goat to get it to change its mind. More generally, you know how lawyers cling to WordPerfect because of the magical “Reveal Codes” functionality? Well, working in a lightweight, text-based, markup language like Markdown is like having reveal codes turned on all the time, but it doesn’t obstruct your ability to see the text!