Writing Novels and Non-Fiction with Visual Studio Code

You’re thinking — whoa, hold on there, what?

Aug 2021 Update: It’s been a while since I wrote this article. I now swear by it! When paired with PublishQuickly (I’m a beta user — it’s an online no-install Markdown to Kindle Word or ePub creator with many other features) this has been a game changer for me in terms of writing productivity. I have now published a total of 7 full novels with this system (> 400,000 words) and this will be it for the foreseeable future.

TL;DR

Used Microsoft’s Visual Studio Code to write novels, and it turned out to be the best thing I did. Read below for all the details on my working system.

If you want to follow my method, here’s three things you need (I repeat them in the end):

1. Learn Markdown in 10 minutes
2. Go grab MS Visual Studio Code to do the writing part
3. Get yourself a free account in https://PublishQuickly.com to do the metrics and close-to-publish-ready word doc generation

If you’re a new writer struggling with writing fast or getting ready to self-publish, I recommend you try this system.

I’ve revised some content to reflect the latest as of August 2021

Introduction

Many writers (and I’m talking fiction and not computer programming) have probably not even heard of Visual Studio — is it a graphics program? Is it studio software? But those who have might wonder how a programming editor can possibly be good for writing books.

Well, someone had to go there, and I did. Brave and the bold. Or maybe just stupid. In hindsight, it was not stupid at all. All my novels (The Whispers of Atlantis series and the Cleopatra series) have now either been revised, or written entirely, using the approach described below, using Microsoft’s free Visual Studio Code programming editor.

Before someone thinks what’s wrong with me, here is my journey with writing tools:

• first, I tried Microsoft Word
• then, I went to OneNote so I could better organize the manuscript before packaging for publishing. My post on using OneNote for Novels is pretty popular
• then, I tried Scrivener — briefly — an established tool for novelists with customized features for writing
• after that, I dabbled with Ulysses — an excellent software for Mac and iPad, customized for writing needs. I wrote significant parts of The Wrath of God with Ulysses.
• I also briefly flirted with Bear, a beautiful markdown editor and note taking tool
• and then I returned to Microsoft Word because I found myself restricted by certain aspects of Ulysses

But each time, I felt constrained by something or the other

• Difficulties in managing chapters, writing speed, moving things around, navigating, creating beta versions or boxsets, wasting time on formatting too early in the process
• Inability to easily get robust metrics (I’m a bit of a numbers guy), keeping track of development history
• Lack of content portability (getting tied into proprietary formats)

Each of these ultimately impacted productivity, because writing and publishing a book is not just about “writing.” There’s a lot that goes into preparing a book for Amazon or elsewhere.

A typical Writing Process

1. Writing
2. Polishing the work (grammar, pacing, rewrites, reviews…)
3. Understanding the writing metrics to smooth out rough edges (unbalanced POVs, excessively long chapters etc.)
4. Getting it beta read with multiple people, revising
5. Sending for proofreading or querying
6. Exporting to publishable formats (word, epub, mobi, pdf…)
7. Publishing

Now, consider the effort and complexity when manuscripts are 80–100,000 words, split into 50+ chapters. And multiple such books. It gets a bit hairy.

I also found it really hard to update my backmatter and book lists of each book after I released a new one. It was also challenging to bring all books to the same look and feel if I wanted to revise. Could I separate content from format?

So, I finally thought, could an old guy (alright, I’m not that old) think of using some of these fancy programming editors that come with a lot of useful features? I’m a tinkerer by nature and enjoy trying new things.

And that’s how I jumped into using Visual Studio Code for writing my manuscript. Here’s what attracted me to it.

What attracted me to Visual Studio Code

1. It’s free and well maintained
2. Excellent “extensions” system to extend the capability of the editor
3. Great themes that make writing pleasurable
4. Zen/Focus mode
5. Ability to write my chapters as simple text files and keep it organized on my folders and Cloud — ultimate portability
6. Ability to do version control (ooh, we’re getting fancy!) — I use GitHub to do all my revisions on it
7. Ability to write scripts that can analyze chapters and provide valuable metrics, or even automate several tasks… I use an online version (I’ve used other versions before) called PublishQuickly to go from a Markdown file to useful data

How I organize my work in Visual Studio Code

Nothing complicated at all, really.

The critical thing about my setup is I write using Markdown. This is a simple text format, really easy to learn, and you can then transform the text to many other outputs including Word and ePub (which I do using an online service).

My setup is very simple:

manuscripts/
 the.last.pharaoh.regent.md
 the.last.pharaoh.queen.md
 the.last.pharaoh.empress.md
 ...
resources/
 tlp.map.png
 tlp.cover.png
 ...

when I’m close to finished on writing, I begin to process it using PublishQuickly.

The Results

How did it all work out?

Very, very pleased!

I finally have my work organized exactly like how I want and I’m faster and more efficient than I ever was with the other editors.

I focus on the writing and only when almost 98+% done do I switch to another tool to take it to the end. (all I do in Word is minor formatting tweaks)

My process chain is:

Write in VS Code using Markdown -> Produce Docx through PublishQuickly-> minor tweaks to the Docx -> Upload to Amazon KDP

Here are ten things that made this really valuable for me:

Read this list and at the end of it you can watch a series of very short YouTube videos that shows all this in action!

The Ten Features of Visual Studio Code I use for Writing my Novels

1. Fast writing and Powerful Extensions — the autocomplete feature enabled by the All Autocomplete extension can enhance writing speed and reduce writing errors; extensions to help with Markdown writing, live preview, and many, many others
2. Beautiful dark theme — (Pitch Black) which is easy on the eyes, and the ability to customize themes and fonts. I’ve since tried other beautiful themes — my current favorite is Horizon. It’s wonderful.
3. Excellent Markdown editor with CSS customization and live preview that scrolls in sync with the editor. An outline view is a superb navigation feature that lets you jump to sub-sections (particularly helpful for non-fiction, academic or computer related writing)
4. A Zen Mode that keeps focus only on the editor
5. Ability to see chapter words, spell check, fast search, global search, and search-replace
6. Integrated version control — I can save versions of my chapters as many times as I want, and go back to any version I want
7. Works on files on the folder, which means I can open these files from any editor, including simple notepads, wherever and whenever, and continue to work. For example, on iPad, I use GoCoEdit. It’s this ability to work on simple text files that also makes it perfect for scripting against it.
8. Split editor — open multiple versions, same chapter in two places, reference files, todos — whatever you want. In fact, the split can be more than two — if you have a large monitor you can have 3 vertical splits with each having a horizontal split, or a 2 x 2 grid…
9. Line number and right side mini-view that’s great for navigating large chapters and going back and forth
10. VIM mode support — most people won’t know about this outside coders. But this is a fantastic writing emulation that lets you write and navigate text files really fast using just keyboard strokes. It takes a little getting used to, but once you get the hang of it, it’s amazing! I cannot stress this enough — Vim has truly powered writing for me.

I bet I haven’t even explored many other tips and techniques, but I will update my findings as I go.

Disadvantages

Working with an editor made for programming comes with some disadvantages, some of which might be deal breakers if you are unwilling to make changes. Here are three that come to mind. None of these proved to be deal breakers for me.

1. Not designed by default for writing. Unlike Scrivener or Bear or Ulysses, there are no built-in presets or specific features for writers (like exporting to multiple formats, separate note-taking, chapter organization, etc.) But personally, I ended up not using those features much, and their value diminished.
2. No mobile support — there is no Visual Studio Code for iPad or Android or iOS. You’ll need to find another Markdown text editor (I use iaWriter on my iPad) that can connect to your Cloud account to edit the files. Perhaps this will come someday. I’ve heard of VS code in the Cloud, but I prefer to work on files on my computer.
3. No in-built document formatter — e.g., bold, italics etc. You write in text, but you can use Markdown to get most of those features. Markdown is really simple! (Some of the themes in VS Code, like Horizon, do a pretty good job of coloring the text based on the formatting — like bold and italics, and it’s good enough)

Using with Grammarly

Just import the specific chapter in Grammarly, make the fixes, paste it back. This is particularly useful for those who write on Mac because there is no Grammarly support as an add-on on Microsoft Word.

The idea is that you do 90% of your book writing on VS and then do the final formatting in whatever tool you want. You have to do that with pretty much any writing tool anyway. None of them get you to 100% readiness right away.

Proofreading

VS code makes proofreading very effective too! Read this article I wrote on how to proofread using text-to-speech and modified formats.

What Next?

If you want to follow my method, here’s really three things you need:

1. Learn Markdown in 10 minutes
2. Go grab MS Visual Studio Code for free
3. Take a look at https://PublishQuickly.com

And then start writing.