Over the course of 2016 I have traveled a long but (surprisingly!) easy journey to simplify my writing practices by eliminating distractions from as much of my design tools as possible. Most definitely the biggest and most drastic change in this process was moving away from my go-to standard of Microsoft Word, and instead adopting the Markdown language as my new main writing format. I’ve mentioned this a bit over the past few months on my Google Plus stream, and have had numerous folks ask me to do a longer write-up on my experiences with this dev process transition. To that end I’ve written this feature to lay down the basics of my process shift, and encourage others to do similarly to simplify their own methods. Even this post is written in Markdown!

My Life as a Former MS Word Fanboy

Until this point I have been a pretty die-hard seemingly-life-long MS Word fanboy. I was at one point a notorious MS Word blow-hard in my circles, in fact. I was trained to use Word in a pretty intense legal environment, and through that training learned pretty much every trick that software had. I was a mouse-free keyboard whiz with docx files, and quite proud of it. Word was my Jam, and I will probably be mentally cycling through my most-used shortcuts until the day I lay on my death bed.

However, perhaps my biggest flaw as a technical creative is that I’ve always been pretty inconsistent with version controlling my documents. In my former design flow, “version control” really only meant “I’ll make a manual numbered backup copy whenever I remember to get around to it,” paired with occasional recursive date-stamped tarballs of my entire Dropbox directory. Heck, I remember speaking on a game design panel at a local convention a few years back, loudly advocating for this method of version controlling because things like Subversion were just too irritating and not good with binaries. I kick myself today for those recommendations, of course, and publicly apologize to any of the poor folks at that panel who may have been swayed by my words (although truth be told, no one else at that panel actually had any better suggestions, and that is even sadder). This DIY method just isn’t efficient by any definition of the term, and can become difficult to track and record over long projects, especially when those projects span multiple years and numerous working computers. The introduction of file-synching services like [Dropbox][dropbox] will certainly make it easier to keep multiple working devices up to date with the latest versions and edits, but it does little to solve the deeper conundrum of proper versioning.

Last year that all changed when I started working at Puppet, which is most definitely a “Git shop.” Although my prior experience had been entirely with the Subversion tool, and I had by then grown basically used to its eccentricities, after my first on-the-job exposure to Git I was hooked. Code commits and revision became close to the stuff of dreamland happiness, and I converted all my existing subversion code repos immediately, never looking back. This sudden revival of interest in version controlling inevitably got me reconsidering it for my own game design work, and I set to task looking for ways to make that work.

However, when I finally made the decision to introduce Git into my work flow, I was immediately dismayed to learn that Word’s .docx format does not play well with Git. There are work-arounds, yes, but they require heavy process customization and additional steps that are so involved and round-about that they end up defeating the whole point. I needed to be able to work both easily and efficiently, while also maintaining peace of mind that my designs are completely tracked and easily revert-able. After numerous attempts to jam a struggling pig into a Pez dispenser, I had to eventually accept that if I wanted the benefits of precise line-by-line version control for my game design docs, then Word would no longer work for me.

Introducing Markdown

I can’t fully recall exactly when I was first introduced to the Markdown language. I suspect it may have been when I first started using Simplenote as my preferred bullshit-free cross-platform notes app, but it might have also been encountered in some random wiki I once used for gaming (although most of those use Textile, but anyway). Either way, my reintroduction to the language coincided with my aforementioned introduction to Git, as several of the other tools we use in-house here support Markdown formatting. It wasn’t long after my re-exposure to it that it began to click: hmmm, I wonder if this would work as a Word substitute?

Well, clearly, this article is my answer to that question. And hopefully it will be a suitable guidepost for anyone else seeking a similar simplicity in their design process.

Why Markdown?

While I’m not going to use this space to write a lengthy report on why you should use Markdown (I hope the above link tells you all you need to know about that), I will tell you why it works for me, specifically. In case you didn’t know, I also dabble in writing code. As such, I’m used to the concept of in-line formatting characters, and comfortable reading them on the go. I suspect that most of you who have experience hand-writing code and markup have similar methods, and are likewise comfortable with in-line markup presentation of your work. As such, eye-scanning unrendered Markdown text is just as easy as scanning a style-formatted Word doc.

Markdown is a ridiculously versatile documenting language, supported pretty much everywhere, all over the internet. Thousands of content sites allow it in posts and comments, and if you’re using the fairly ubiquitous Jetpack plugin, even WordPress supports Markdown – this entire post was written using it, in fact. How neat is that! That extreme portability of the language is one of its biggest appeals to me. Every single different Markdown editor I tried in my quest for perfection at least let me export to HTML, and most of them supported PDF, ODT, and DOCX as well. With tools like Pandoc, that export compatibility is extended even further to a great array of different formats both common and obscure.

Definitely the biggest plus for me, however, is the fact that Markdown-formatted files are saved in plain old text format. This makes them perfectly compatible with git-based version control practices, allowing for line-by-line change comparisons and revisions. This core feature allows me to have the best of both worlds: readable and publishable style formatting without need for saving in binary format.

Markdown Editors

In order to truly ditch Word and cross over to the Mark Side (don’t shoot me), you need a good editor. In a pinch, it’s pretty likely that your current favorite text editor already has plugin support for it, and even without it you can likely just get by writing in plain text if that’s your jam. Personally, however, I wanted a good Markdown-focused editor to replace Word, with minimal built-in distractions and just enough features to keep me working comfortably. My biggest needs are simple enough:

• Minimalist interface options (necessary for maximum productivity)
• Line Numbering (crucial for large files and git log cross-references)
• Header outlines (needed for quickly navigating large documents)
• Live/Toggled Rendering Preview (need to have an idea how it will look!)
• In-line basic formatting (visual effects of active text formatting)
• Support for multi-doc editing (either tabs of multi-window support)

I can sacrifice one or two of those if absolutely necessary, but ultimately seek perfection. However, in truth my own needs are a bit more complicated than just that. I suspect I may be something of a fringe case here, but I frequently work at a large number of different machines, running Windows, Linux, MacOS, Android, and iOS. I need to be able to port my work across any number of operating systems depending upon where I am and what machine I’m using when my writing inspirations hit me. To that end, I needed to track down either one amazing once-in-a-lifetime cross-platform app that fit every need, or multiple “close enough” applications for each individual platform. I was really close to achieving the former, in fact, but in the end there were enough inconsistencies that I finally opted for the latter platform-specific approach. While your needs may be different, below are my results and the apps that currently (as of publication, and I may revisit this in the future) work best for me.

For Windows (my primary operating system) I have tried a lot of different apps, and am now torn between two specifically. After a long series of disappointments, including some I paid for and now consider lost money, the two most compatible apps for me are Markdown-Edit and Ghostwriter. Both have a nice array of features, and are mostly feature complete as far as my above list of needs goes. Lately I’ve been leaning toward Markdown-Edit, primarily because it has a few more necessary features for my process. The developer of Ghostwriter is very active and quick to respond to issues, but I suspect my own needs are a bit divergent from his design goals, and in the long run I’ll need to work more in the prior app. However, both have active github sites, and are open source, which is always a big plus for me.

For MacOS I have found Macdown to meet most of my needs, and during the occasions in which I am unable to remote connect to my home Windows workstation, it serves respectably. Ghostwriter (mentioned above) also has a Mac version, but I’ve not used it and can’t comment on its effectiveness.

For Linux I use the Remarkable app, and like Macdown is is suitable for when I can’t otherwise open my home workstation. However, in Linux I tend to find myself favoring Vim for a lot of my editing, and there are a good number of Markdown-focused extensions for that program – way too many to bother linking here. If you’re a Vim user, you probably already know how to find those for yourself.

I have unfortunately yet to find a decent Markdown-specific editor for Android or iOS. At least on iOS there is one nice little gem called Git2Go, which is a combination of git client and text editor. It has built-in text highlighting for some languages, although Markdown isn’t yet one of them (I’ve been pestering the devs to add it though). But it has the ability to sync with multiple git repos and hosts, which is crucial for my needs. And for both of these platforms there is always Simplenote…

Let’s Talk About Simplenote

Simplenote is goddamned awesome, there, I said it. I’ve yet to find a more bullshit-free universal note-taking and synching application. It has clients for Win, Mac, iOS, Android, and even Linux. It can even be accessed on the Web, in case you can’t install the local app. There’s even an awesome third-party app called Resoph for Windows which allows for the option of complete plain-text automatic note dumps, and comes in a portable thumb drive option.

So why mention Simplenote in this post? Because Simplenote has fully-functional built-in Markdown support! You can Markdown-ify any of your otes in both the Simplenote apps and the third-party Resoph app, and toggle previews of exactly what your file will look like should you publish it. Not only that, but Resoph’s plain-text automatic exports are also 100% git-compatible, allowing for line-based version comparisons and commitment to control. Whenever I happen to find myself lacking a suitable Markdown editor and/or git client, Simplenote is a wonderful fallback, allowing me to add or modify text on the fly and commit later when I’m back at a more functional workstation. And with a little creative bash or powershell scripting, even that can be automated.

I have friends who swear by Evernote or other such apps, and I recognize that they definitely have their uses. But when it comes to design, for me plain text is the way to go, and Simplenote’s distraction-free writing interface wins my vote.

Git Yourself some Version Control

So I keep talking about Git, but I imagine you may be unfamiliar with what exactly git does. Here is a fantastic video which explains the structure and concepts in wonderful ways, in the form of a presentation delivered by a real-world associate of mine. It’s long, but it explains the whole thing in pretty nifty ways that helped me a lot at first as well. In short, it’s a version-control system that kicks ass and is actually super easy to use once you get past an early learning curve. Git can be acquired from the main Git website, and there are installs there for every major OS. You can also search for other ways to install via your package manager of choice, too.

Git can work as a local-only solution, but truly excels when paired with an upstream “remote” server for off-site backup and cross-site / cross-platform syncing. This is especially true if you’re working with a team. Some people swear by community-favorite host GitHub, and I admit it’s pretty easy to use and supports a vast community of Open Source developers. Personally, I prefer Bitbucket, mainly because it gives you private repos for free, whereas GitHub charges you for them on a monthly basis. That said, GitHub is the most active, and it’s where I publish all my open stuff for maximum appeal.

There are a number of frontends available for users who prefer a GUI experience, really too many to name. I already mentioned Git2Go for iOS, which I love. GitHub has their own Desktop interface which is pretty cool, and there’s also the really solid SmartGit if you’re into commercial apps. I previously was a big fan of an app called GitKraken, but since they now require a third-party registration with their central servers, I no longer use them and encourage you to stay away. That’s just a shady practice in my opinion.

Other Bits and Pieces

A few extra apps round out my current toolbox. Since I’m working on Windows primarily, I should give a shout out to MobaXterm, a commercial terminal application for Windows systems that provides some really cool features. It’s really just a cygwin frontend with a solid SSH management system built-in, but I really enjoy the basics of the interface and it’s pretty much my second home these days while working on my main machines.

If you’re working with tables, and want to convert your tables from Word docs to Markdown, this web-based tool is indispensable. It provided a great amount of assistance in my process of converting Cannibal Contagion to markdown. I keep it open in a tab every time I’m working on major document updates, and it’s probably the most-used site in my list of Markdown reference links.

Oh, and did I mention Simplenote?

Final Words

It should go without saying that the things that work for me won’t be suitable for everyone. Some of you are perfectly happy with your existing processes and have no need for change. And some of you will likely be die-hard Word fanatics until the end of days, and that’s fine! But hopefully this post helped someone find a more fluid way to design their games. And hell, some of you may already do this with your own work, and already have ideas for improvements that I have not yet found. If you do, drop a comment and let me know, and maybe my own work will improve even further.