I’ve long enjoyed a love-hate relationship with Scrivener, the all-in-one writing platform for novels, short stories, textbooks and other written endeavors. I love it because it offers excellent outlining and note-taking features, plus it integrates with programs like Scapple for mind-mapping and Aeon Timeline 2 for timeline management. Scrivener supports many different compile settings, so exporting content is never a challenge.

I hate it, though, because Scrivener’s full-screen editor is abysmal—the worst “distraction-free” implementation I’ve ever seen in any app that supports this feature—and because Scrivener projects are essentially a giant cluster of Rich Text Format files named by number and stored in a byzantine file-tree structure, separating me from my work by requiring the application to mediate my content.
My preferred approach to writing is to enter a full-screen, distraction-free mode. (Usually after dark, in an unlit room, working with an amber-on-chocolate color scheme, with soft music playing and either the windows open to the breeze or a fire roaring in the fireplace.) Over the years, I’ve played with different approaches to writing in Markdown and AsciiDoc with a dedicated text editor, but these efforts haven’t proven satisfactory because the apps tend to take a single window and full-screen it, cutting me off from my notes.

Until recently, that is—for now Microsoft’s Visual Studio Code allows for multi-pane windows, even in distraction-free mode. I know you can open multiple simultaneous buffers in Emacs or whatnot, but my willingness to learn Emacs or Vim syntax remains too weak to justify the technical debt of mastering these systems just to write. So VS Code, which is much simpler, fills me with joy.

I played with it and got hooked. And because VS Code does a great job of working with the git system, I explored even more deeply with version-control on my text documents. I’m now far enough into the process to have decided that I’m migrating all of my writing out of Scrivener and into my new infrastructure.

I’ll share how I set up this environment in the context of a book I’m writing about healthcare data analytics, and then why I think plain-text writing with version control makes more sense for complex writing projects.

The Setup Process

After initial testing seemed favorable, I created a DigitalOcean droplet with a one-click install of GitLab Community Edition. GitLab CE is a free, open-sourced platform for storing and sharing computer code, with enhancements designed to make the code-writing job easier. I’m paying $10/month for the DO droplet (a droplet is a virtual server, in this case, an implementation of Ubuntu Linux that already has GitLab CE configured on it, so I didn’t have to do any tedious manual installations). I use DO to host this website, and the jegillikin.com domain name, so I mapped the new droplet to a subdomain—code.jegillikin.com. This approach is significant because I can add new users to my GitLab environment with permissions to participate in one or more projects as collaborators, without having to email Word documents back-and-forth. Less tech-savvy collaborators may simply use the built-in Web editor to work, without having to download or install or configure anything.

It took roughly 10 minutes to fine-tune the GitLab installation after the droplet was set up. Perform the usual Ubuntu security-hardening steps, and voila. Good to go.

I downloaded the most current release of Visual Studio Code (the app receives updates monthly) and then installed a few specific extensions to make my drafting process easier:

• Active File in Statusbar—to show the file path in the status bar
• Amber Theme—the colors I want, amber-on-chocolate
• AsciiDoc—adds rich language support, syntax highlighting, live previews and snippets for AsciiDoc files
• Better Comments—manages specific comment types with configurable formatting
• BibManager—Manages BibTex bibliography files
• bibtexLanguage—adds syntax highlighting for BibTex files
• Bookmarks—ability to mark specific lines and then jump between them
• Clock in Status Bar—adds a small clock, useful in the distraction-free mode
• Code Settings Sync — syncs your complete configuration to GitHub (not GitLab) so you can clone your setup on a different computer or a re-installed computer
• Epub Tools—inserts epub-specific syntax and output support into VSC
• Git History—views the git log and file history to compare versions over time, within VSC
• RTF—adds native RTF support to VSC (helpful if you’re migrating RTFs from Scrivener)
• Spell Right—a lightweight spell checker
• Todo Tree—shows your comments (todo, fix, cite, etc.) in a project-level tree
• VScode-Spotify—integration so I can manipulate a Spotify playlist from the VS Code taskbar (so no more getting out full-screen mode just to adjust my tunes)
• VScode-Timer—a simple configurable countdown timer that sits in the statusbar
• Word Statistics for Text—runs a frequency analysis by word on a particular file or folder
• WordCounter—a counter, in the status bar, showing the number of words, characters and lines, as well as the estimated reading time for the file
• YAML—support for YAML blocks (helpful for ePub files)

I also tweaked a few VS Code stock settings to my liking, including font choice (I’m a fan of monospaced fonts for writing, so I use Liberation Mono) and color swaps for the statusbar.

You’ll also need to down the Github for Desktop client. The Github client works just fine with a GitLab server. The client installs git on your computer. VS Code uses git to push and pull content between your local machine and the GitLab CE server.

With the server and the software configured, the next step was to create a project. More than one way to do it. I opted to create it in the GitLab CE control panel, then I used the Github for Desktop client to clone repository, selecting the URL of my GitLab project and a folder on my PC. (Bonus: I sync the local folder witihn my OneDrive structure, so there’s yet another cloud backup lurking out there.)

Using AsciiDoc

AsciiDoc is one flavor of a text-based markup language. In AsciiDoc, writers focus on the text, not the formatting of the text. It uses a straightforward syntax for noting formatting through coded characters. For example, to italicize text, wrap it in a pair of underscores. To indicate a header level, prefix it with an equals sign.

AsciiDoc requires installation. The most common toolkit, AsciiDoctor, requires installation of Ruby on your local machine, but the stock tooklit requires Python 2.6 or higher.

Writing in plain text with markups offers several advantages over writing with a visual word processor:

1. You’re not distracted by how the words appear on the page.
2. Using markup elements like underscores and asterisks permits fine-tuning of formatting moreso than double-clicking text.
3. Elements like admonition blocks (text call-outs like “warning” or “note” boxes) require no additional work.
4. The appearance of the final document is governed by a stylesheet, so you need not fuss with formatting while writing.
5. Plain-text files support version control to facilitate collaborative writing and to avoid 85 differently named copies of the same file.

Some people prefer Markdown or MultiMarkdown for plain-text writing. Although I first started plain-text writing in MMD, I learned the hard way that the Markdown syntax consists of too many competing flavors with too weakly typed of a syntax. AsciiDoc is much more strongly syntax-coherent, and as a bonus, it naturally outputs to formats including HTML and DocBook.

(DocBook is significant. It’s essentially a giant XML file—but one that cleanly imports into Adobe InDesign for layout with the hard structuring work already complete.)

The Writing Process

With a cloned repository, whatever you write on your local computer—as long as the file is stored in the folder you selected when you cloned it—will sync with the server. Unlike tools like OneDrive or Dropbox or Google Drive, syncing with git isn’t automatic, however. You only sync when you want to. When you do sync (in a process called a commit), you’ll be prompted to add optional change notes. I find it helpful to offer a sentence or two summarizing what I just did. Every sync creates a new revision, or current-state snapshot of the project, and all of those revisions are maintained. So if you work on the same chapter over three months and commit changes 36 times, you’ll be able to check all 36 versions and even compare them—like “what’s different between version 23 and version 32?”.

That said, writing is straightforward. Just write. Don’t worry about formatting or margins or fonts: All of those concepts are superfluous during the drafting process when you’re working with Markdown. Instead, just write. And commit changes frequently. Any specific formatting requirements, like headings or bold/italic typefaces or lists, are effected in a straightforward manner using AsciiDoc syntax within the file.

Why AsciiDoc Plus Version Control Rocks for Complex Writing

One thing’s for sure: You must be reasonably comfortable using a text editor (instead of a word processor) to write in order to thrive in this production model. And you must possess some expertise in working with a version-control system, although you’re free to either use GitLab’s free online service or subscribe to GitLab or GitHub so you don’t need to run your own server.
But the benefits to this drafting process are substantial:

• Although Microsoft Word is a very capable application for writing complex long-form projects, not many users know how to use Word optimally. As such, file corruption and the need for complex reformatting can suck away at precious writing/editing time.
• Version control means you don’t need to save a billion different copies of a file, each with a slightly different name. And, you can compare those files easily. And because your files are committed to the repository, you don’t run the risk of losing “all your work” if your thumb drive gets lost or your hard drive crashes.
• A VCS with an online portal—like GitLab CE—opens the door to tightly controlled access to specific files, protecting your intellectual property and facilitating broad collaboration with other contributors, without the need to email drafts back-and-forth and then harmonize them by hand. In fact, GitLab CE contains an issue-management system, so edits and questions remain with the project and accessible to all contributors.
• Tools like VS Code (and, admittedly, Emacs, Vim, Notepad++, Atom and countless other text editors) support high degrees of customization, so you can write how you want without being locked into the fixed interface options of Word, Scrivener, etc. Don’t be misled into thinking that text editors are only for hard-core computer programmers. Plain-text writing in Markdown is absolutely a valid and supported use case for these software platforms.