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:

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:

Writing tools - options #

The initial options I'm considering are:

Integrated Development Environment #

Visual Studio Code, as:

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:

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 #



Since you've made it this far, sharing this article on your favorite social media network would be highly appreciated 💖! For feedback, please ping me on Twitter.