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.
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.
I expect that I will write on the following platforms:
- blog: a static website made with Hugo
- book: LeanPub (and possibly an accompanying course)
- git: any/all of:
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
The initial options I’m considering are:
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.
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.
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.
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).
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.
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
- Pro Git book - available to read in the browser, or download an ebook format
- Atlassian has excellent tutorials on learning Git.
In Visual Studio Code, I find these extensions very helpful for working with Git repositories:
- 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.