Writing with Markdown and Git

In three recent roles (two paid, and one voluntary), I estimate that I’ve written 300 or so internal technical and procedural documents using Atlassian Confluence.

When I left a recent role, a colleague was kind enough to give me a book - How to Make a Living with Your Writing, which has prompted me to at least start writing in a more structured way.

I want to be able to make use of smaller snippets of time, so I’ve spent some time thinking about which tools will allow me to write quickly, without forcing me to use a different tool simply because I’m writing a blog post as opposed to a chapter of a technical book.

Destinations

What I hope to write:

  • a blog, hosted as a static website.
  • a book, which can be exported to multiple eBook formats, particularly PDF, ePub, and mobi.
  • fast-moving technical documentation on Atlassian Confluence.
  • code and README documents in Git repositories.

Platforms

I expect that I will write on the following platforms:

Writing tools - requirements

I want to be able to write with any/all of:

  • an Integrated Development Environment on a computer - ideally installed without needing admin permissions
  • a dedicated writing focus tool - possibly with an accompanying app
  • an app on my phone - mainly for capturing thoughts, rather than extensive writing
  • web-based tools for lightweight writing / editing, if for any reason I’m using a different computer

Writing tools - options

The initial options I’m considering are:

Integrated Development Environment

Visual Studio Code, as:

  • it’s free.
  • it’s under constant development / improvement
  • it has some excellent extensions, particularly making my work with Cloud systems easier.
  • I usually have an IDE open on my computer, so there’s no friction in opening a separate writing tool.

A dedicated writing focus tool

The professional choice

I believe that the “professional” choice is Scrivener, which looks great.
Joanna Penn who wrote How to Make a Living with Your Writing, even uses it for book marketing.

It looks comprehensive - there’s even a course on learning how to use it well. I know that my own tendency would be to spend my discretionary writing time on becoming good at using a writing tool, so I’ll look for a lighter-weight choice.

A tool which does one job really well

I like tools to do a single job really well. IA Writer’s sub-heading is “Plain text. Full ownership. Total focus.”

The corresponding app looks good, and if I were writing on a larger phone or a tablet, might be a compelling choice.

Writing tools - choice

Markdown

Given the additional requirements above, Markdown is the obvious choice. If you’re new to Markdown, or it’s been a while since you last used it, this 10-minute tutorial is helpful.

For several years, I wrote most of my documentation using Confluence Wiki Markup, so I’m used to (and like) shortcodes.

Markdown is of course a markup syntax, which is supported by a wide variety of tools (and is “only” text).

Markdown tools

Visual Studio Code - Markdown

In Visual Studio Code, I find these extensions very helpful for writing Markdown and checking it is well-formed:

There’s an excellent guide for working with Markdown in Visual Studio Code including how to install extensions.

iPhone apps - Markdown

I tried a few iPhone apps, and settled on Editorial for a few reasons:

  • it costs £4.99
  • “Workflows” allow Editorial to be customised (and for instance, send to Working Copy)
  • it links to Dropbox if required

Version control tools

Dropbox can be very useful as a synchronisation tool, (and can even be a way of getting content into LeanPub but for my needs, I’d like to use Git version control.

Learning Git

Git version control tools

Visual Studio Code - Git

In Visual Studio Code, I find these extensions very helpful for working with Git repositories:

iPhone apps - Git

  • Working Copy, with all its integrations. I think this would come into its own with a larger screen. The free version is excellent for occasional cloning. At £15.99, it’s more than a casual purchase, but I’ll update this page when I convert to the paid-for Pro version.