On walkabout in life and technology

The Markdown Payoff

A long, long time ago in a galaxy far, far away, I switched to Markdown format for documents, notes and other scratchings. (And wrote about it - see the posts in the Markdown category).

Was switching to Markdown a good call? Did it pay off? And if so, how?

I actually wrote this post not knowing how it would turn out. I wanted to know for myself if it paid off, or if I just followed a fad. A fun exercise.

BM (Before Markdown)

Before Markdown, I wrote less. I rarely blogged, took occasional notes using pen and paper and often forgot things. If it was not sent via email, I did not have it. Sounds familiar, no?

For plans, manuals and other work documentation, I used Microsoft Word, just like everyone else (See Why Microsoft Word Must Die). I was one of those people who used document styles, but still found myself spending heaps of time formatting my work and then reformatting after other people’s edits.

For everything else, I scribbled notes in a cheap, paper notebook that I never read, on post-it notes that stacked up or on the back of printouts (remember when we printed stuff?) that got thrown out.

Other than after-the-fact documentation, I had no useful records of meetings, designs, thoughts, decisions or what I did. And remembered little of what was said, why things were done or what was done.

It was because I did not have these things that I looked for a simple solution, one that would work for me, and I found Markdown formatted files. I created my own Markdown Mindset

AM (After Markdown)

Since I started writing Markdown formatted files, I have created lots of them: meeting notes, assembly notes, support notes, design decisions, journalling, project documentation, business documents, ideas, proposals, statements of work, contracts, README files, server configurations, copies of quotes and even to-do lists. Everything that I may have written or jotted down is now in a Markdown file. And everything that I was to lazy to record, I now do, in a Markdown file.

I write more. In fact, I write a lot more. I take my laptop (and now iPad) into meetings and take notes that I save. I have BBEdit open at all times with the current project’s notes open, and habitually switch to it to jot down thinking, ideas or even the commands I use. If I get interrupted, I jot a note in a blank Markdown document.

Because I have these files available at my fingertips, I can always get back to what was discussed, what I was thinking or what I did. All the valuable (and useless) information previously lost in the write-only notebook, the stacked post-its or the missing printouts is saved and searchable.

I write everything using Markdown. I write my blog using Markdown in Byword. I write my specifications and longer documents in Markdown using Scrivener. I write everything else in Markdown using BBEdit. Add these all up and the cost is still less than a copy of Microsoft Word.

But is all this paying off?

Payoff Wins (Quantitatively)

The payoff is quite measurable. Binary in fact. I have the information I need and I can find it. Versus not having it!

I have created over 1,600 Markdown files over the past two years. That’s a lot of note taking. I often find myself searching for – or going back to – these notes so see what I did, what I was thinking or what, and most importantly, why decisions were made. Having the information helps resolve disputes or explain why things were done.

If having these files is good, being able to find them by content is better. Paper notes are hard to search. Markdown files, being plain text, are perfect for Spotlight search (or whatever indexing your Operating System uses). I can type in a search phrase and all the matching notes are right there.

To aid search, I use Markdown Metadata to tag files and add keywords (and sped up using Keyboard Maestro macros). To aid in selection, I use a file naming convention (see Text Notes - Going Electronic) that identifies the file kind (meeting, note, idea, etc) and its project and date (and sped up using TextExpander snippets).

The quantitative payoff is clear, I have the information I need in a portable and searchable format and I can get to and create these very quickly, efficiently and productively.

Payoff Feeling (Qualitative)

The quantitative payoff, however, comes from the qualitative payoff. These files exist because I have the discipline and tools to create them. And the discipline exists because I want it to.

Since switching to Markdown, I want to write. I want to take notes, I want to record my thoughts and ideas properly, I want to document things. And after two years of doing it, I still want to write. This is no fad. Markdown takes the hassle out of writing, and removes the barriers to get started.

Not only do I want to write more, I want to write better. I’m a programmer by trade, not a writer (as can be divined by the quality of writing in this blog). But because I write more, I want to become a better writer. I want my documentation to be clearer and appear more professional, my blog posts to make more sense and even my emails to be more concise. I feel that as a better writer, I can be come a better communicator and that is best for all.

The key to Markdown writing is that you focus on the content. Structure, format, look and feel are all secondary. It’s pure distraction-free writing. Which means that you have no choice but to write and think about writing and focus on the content. Which encourages you to become a better writer.

The other issue with writing is that it takes time, but the payoff of Markdown is that you land up spending less time doing it. With no distractions and fast tools, more writing gets done. What you do with the time you gain is up to you, but for me, it means I write even more.

And since I want to (and do) write more, I lose less, forget less and understand more.

The qualitative payoff is that you want to write, you therefore write more, leading to having more notes available when you are looking back.

The Payoff

To answer my starting questions, then:

Was switching to Markdown a good call? Yes!

Did it pay off? Yes!

And if so, how?

I write more, I write better, and I have the information I need available at my fingertips. I also spend less time writing, almost no time formatting (thanks to Marked), and am more productive because I always know what is (or was) going on.

Follow the author as @hiltmon on Twitter and @hiltmon on App.Net. Mute #xpost on one.