4 minute read

Inspired by this superb blog post by Daniel Schauenberg, I thought it would be interesting to share my writing workflow with you. Since starting this blog in 2012, I’ve streamlined the workflow to become a more productive writer. My goal is to give writing the attention it deserves and focus on what truly matters: producing content. Everything else is secondary.

Markdown all the way down

I write every post in Markdown. I love Markdown for its simple syntax. As a programmer, I’m already used to writing everything in plain text – the most flexible and portable format for data. Markdown is said to fit any workflow. I can say that it definitely works for me.

When it comes to writing, my text editor of choice is Byword. The app’s Markdown support is top-notch. I find word processors in general to be too distracting. Byword, on the other hand, provides a beautiful writing environment that feels like it was made for me.

Additionally, I use Marked for previewing all sorts of Markdown files in their rendered form. I’ve created a custom preprocessor script which adds rudimentary support for Jekyll posts. I also have two shell wrappers in my PATH to make both Byword and Marked easier to access from the command line.

Markdown is also at the heart of GitHub, which brings me to the next section.

Git + GitHub

All of my writing lives in a private Git repository at github.com/mlafeldt/blog. It’s private because I don’t like the idea of sharing unpolished drafts with the world (sorry about that). Besides, I started using the same repository for crafting articles published elsewhere.

I keep everything in Git because, well, I’m a software engineer. Git has never failed on me. It’s impressive technology. I use it every day. The same goes for GitHub (except the part about failing), which is a fantastic platform for software development and, at the very least, a decent one for writers to store and collaborate on prose documents.

As far as Git and GitHub are concerned, writing a blog post and developing a feature are similar processes. For each post, I create a new Git branch along with a pull request on GitHub. As I write and rewrite everything until it all makes sense, I keep making many small commits. One notable difference to programming is that I don’t care about commit messages – I happily run git commit -amWIP all the time.

Sometimes I ask a friend to review a piece before putting the finishing touches on it. Once I feel confident the post is ready for publishing, I merge the pull request via git merge --squash before deploying the update to my blog – but more on that later.

The posts inside github.com/mlafeldt/blog are actually Jekyll posts.


This blog is powered by Jekyll, the static site generator that’s also at the core of GitHub Pages. Jekyll is a blessing for people like me who love to tinker but don’t have any web design skills whatsoever.

I have a couple of Rake tasks to automate the most mundane activities associated with blogging. The ones I use the most are:

  • rake new_draft[title] – Creates a new draft – a skeleton Jekyll post – and opens it in Byword. This allows me to start working on a post right away.

  • rake preview – Starts a web server to preview the blog locally.

  • rake deploy – Deploys the updated site to github.com/mlafeldt.github.io, which gets served by GitHub Pages. The result is what you can see here.

It all starts with an idea

When trying to publish consistently, as I do, it’s important to keep track of writing ideas. I like to collect my ideas on a Trello board. Each card on the board represents a topic I may or may not write about, often capturing nothing more than a couple keywords and relevant links. When I have the urge to start working on a new post, I pick a card solely on the basis of gut feeling and write about whatever topic appeals most to me at the time – for better or worse.

Once I’ve settled on a topic, I run the aforementioned rake new_draft and start outlining in Byword. I jot down whatever comes to mind based on what’s already captured in Trello. My drafts are often quite rough, little more than notes. After I’m done drafting a post, I go over it and try to put everything into proper prose, updating the corresponding GitHub pull request along the way. I will admit that Google and the Thesaurus built into OS X are my best friends for finding the right words when I feel stuck (English is not my mother tongue).

At some point, when I manage to overcome perfectionism, I force myself to hit the big red publish button and put my work out there; which is exactly what I’m going to do now.

PS: With the release of this piece, I’ve managed to publish more blog posts in 2015 than I have in the previous three years combined (15 posts in total). Thanks for reading my words – it means a lot to me.