Baldur Bjarnason

What I learned about markdown from interviewing a bunch of people

– Baldur Bjarnason
A view of my old room when I was at the University of Iceland
This is the only photo I have of my old Mac Performa. Taken when I was moving out of student housing at the University of Iceland, hence the empty shelves.

A prologue, of sorts #

I can’t remember when I first started to use plain text files for my notes and other writing. It would have been some time after 1995 when I was 18 and had recently spent the money I’d earned on my part-time job on a down payment for a Mac Performa.

(I was paying for that computer for years afterwards.)

That computer was an upgrade from my old Mac SE and in many ways, a major improvement:

But, and this is where the story begins to sound familiar to modern Mac users, the software was a different story. However, this time the fault wasn’t with Apple but with Microsoft.

My go-to application on the SE (commonly nicknamed the “kýrauga” in Icelandic, literally “porthole”) was Microsoft Word. Anything I typed I typed in Word. A small black and white screen, Word 5.1, and a mechanical keyboard made for a surprisingly good writing environment.

With the upgrade came a transition to Word 6.0, courtesy of ‘borrowed’ install disks from my mom’s office, and I was not happy.

The performance and UX disaster that was Word for Mac 6.0 is well-documented elsewhere. It’s a textbook case by now. This meant that I began to use Word less and less for personal writing and relied on it primarily for writing for school.

I’ve always written and have always used computers for writing. I began by usign WordPerfect for DOS when I was ten years old. Switched to Word on the SE. And when Word disappointed on the Performa I began to search for alternatives. I tried ClarisWorks for a while. Even tried Nisus Writer.

As you might guess, all this switching meant that file format compatibility became a bit of an issue. And given that most of this was just notes and other personal writing, I eventually settled on plain text and BBedit Lite and have since then mostly stuck to plain text as my primary format for taking digital notes. My use of plain text predates my use of markdown and other markup formats (including HTML).

For work, I’ve always just used what I had to: Word, Google Docs, Pages, whatever. But for myself? Plain text.

The User Interviews #

I had forgotten about all of this when I was preparing for the user research interviews I had set up for my Colophon Cards project.

The interviews were a follow-up to the survey I had conducted a few weeks earlier. I wanted some more context on the data from the survey and to get some feedback on the initial paper prototype of the main view (implemented in HTML, natch). I got around a dozen people volunteering for an interview, which I split into two cohorts:

  1. For the first, I focused on the various kinds of note-taking they were juggling in their lives: collaborative work, individual work, personal, household, hobby, etc. Followed by a short test of the initial paper prototype.
  2. With the second cohort, I tried to dig more into how the various parallel note-taking processes that people used worked together. Were the analogue notes ever moved into digital? Was there a flow between the collaborative notes for work and the individual work notes? Followed by a short test of a new iteration of the paper/HTML prototype.

It’s not the sort of study you do to get conclusive actionable data. Too few participants; too unstructured; a self-selected group of expert users.

That last part is an especially big issue for studies like these. It’s much easier to recruit subjects who have a deep interest in the subject matter, so you tend to end up with a higher proportion of expert users than would be representative of your actual user base. And that was certainly the case here.

These sorts of interviews can be a good source for leads and ideas, though. I view these results more as a starting point for further testing and research.

I wanted some context for some of the bigger questions I had after the survey. One of them was on formats and lock-in. Quite a few of the respondents looked like habitual app switchers and I wanted to find out why.

My motivation was quite self-serving:

So, Why Did Switchers Switch? #

A lot of it is, frankly, down to trauma. Everybody who has used computers for more than a few years has had at least one experience akin to “Word for Mac 6.0.”

The switch for most wasn’t to markdown or a markdown app. They switched to plain text because that format works everywhere with everything. They weren’t switching to markdown specifically. Plain text lets you mix and match apps depending on the platform. You aren’t locked into the same app on desktop and mobile.

This is where expert user bias is important. These respondents were your ideal markdown user: technically competent, curious, and familiar with markup as a concept. They all know markdown and many of them use it regularly. But none of the benefits they described were those of markdown. They weren’t publishing these notes. They weren’t converting their notes to HTML or printing them. What they wanted was the portability and interoperability of plain text. Markdown just made plain text more usable.

If expert users aren’t using markdown for markdown’s sake, what are the chances that a non-expert markdown user is motivated to use it out of genuine interest in a markup format?

To markdown or not to markdown? #

A question that has been rattling around in my head from the start of this project—actually, from the start of my projects at Rebus a few years ago—was whether the writing widgets in the apps I work on should be based on rich text or on markdown?

Markdown has a number of obvious flaws. It starts off simple for most users but its mid-level or advanced features are surprisingly hard to master. Many find it quite difficult, for example, to remember what kind of bracket to use and where. Which comes first in a markdown link, the square brackets or the regular ones? Personally, I can’t, for the life of me, remember how the image markup works. I usually end up embedding an HTML image element. I don’t even know where to start with markdown tables. And I’ve been blogging with markdown for almost two decades.

HTML markup tends to be clearer for many elements, easier to write and read, and less ambiguous. Images, tables, and even links tend to be more straightforward in HTML.

It’s uglier, sure. HTML source code isn’t noted for its typographic aesthetics. But clarity and consistency go a long way.

A bigger issue is that HTML and markdown have drifted apart. Markdown doesn’t have a standard way to markup figure elements. The methods for generating an id attribute, important for cross-referencing, are also non-standard.

But these issues generally don’t matter if you’re writing for yourself and don’t plan on converting the text into HTML or PDF. In those cases, the primary value is the non-proprietary nature of plaintext and the features that markdown provides are just gravy on top. What matters in that context is that non-expert users aren’t likely to be even aware of markdown’s features or even markdown’s existence in the first place. The risk is that you have a bunch of users for whom markdown’s learning curve is so steep that it looks like a wall.

Rich text then? #

I’m not a fan of many of the current trends in rich text editing either.

Block-based editors generally started off utterly dysfunctional because they were, for the most part, flawed conceptually. (Any rich text editor that doesn’t let you select text across blocks is not fit for purpose.) The only way to ‘fix’ most of them has been for them to lose more and more of their unique characteristics. Now, ‘block-based’ has devolved into a marketing term as most of these editors are indistinguishable from their non-block-based counterparts.

Rich text editors today also tend to rely on margin or command menu buttons that are so over-loaded that they make even the most cluttered and ambitious hamburger menu look as clear and straightforward as that of MacPaint in my old SE all those decades ago. Most of them are UX messes overloaded with features.

The minimalist rich text editors, on the other hand, tend to be too minimal. They either rely heavily on hover state for revealing UI elements or just literally expect you to know markdown to activate many of their formatting features. The few that do neither tend to be too spartan and support little beyond basic inline formatting, a couple of heading levels, and image embeds.

Rich text widgets are also notoriously hard to implement properly (usably and accessibly) on the web. They’re extremely easy to get wrong, esp. if you’re trying to roll your own. (Don’t do that.) And if you reuse an existing widget, you tend to inherit whichever garbage UX trend was popular when that widget was first implemented. Markdown, by contrast, just needs a text area. It can benefit from more but doesn’t require it.

Rich-text widgets also raise the spectre of interoperability. People use plaintext for a reason, which is that it works everywhere, with everything, and is readable even in apps that don’t support markdown or other markup formats specifically. You could store the output of a rich text editor as HTML, which has many of the same interoperability benefits as markdown as it’s also a markup format built on plain text. But markdown has one clear advantage over HTML, which is that most of its block-defining markup is either invisible or as-good-as invisible. Paragraphs are defined by new lines. Lists are defined by looking like lists. Even headings are conceptually simple. Even if you had to use HTML for everything else, these block-level features on their own add tremendously to markdown’s usability as a plain text format.

This might not be an issue if you’re just using HTML for interoperability but might become an issue for users who need to edit it by hand for some reason.

You could use markdown as your editor interchange format but then markdown’s multiple flavours and drift from HTML becomes an issue.

So, what? Just give up? #

Surrender means text areas, which means markdown wins by default, except in a way that you can’t market or leverage in any meaningful way.

Instead, I’d like to split this issue into a number of smaller problems to tackle:

The interoperability issues can be tackled, using markdown even, without forcing markdown as a writing tool.

Ease of use is, quite honestly, best served with a rich text editor. They’re tricky to do well but doable.

Power, then, becomes the toughest nut to crack. I think that’s an interesting problem in its own right. You don’t need to resort to markdown to enable power user features in note-taking.

So, I have an angle on this I need to research and pursue, that doesn’t necessarily require me to build a markdown-oriented app.

An epilogue, of sorts #

For most of my life, I had been an avid keyboard user. I hardly ever wrote anything out by hand and had notoriously illegible handwriting. But I had completely forgotten about my initial transition into plain text in the early days of my computing life.

A few years ago, I decided to switch most of my note-taking to analogue. I decided to prioritise my own enjoyment of the note-taking experience over productivity or automation. I switched from being a mostly keyboard and plaintext note-taker to being an avid user of paper, fountain pens, notebooks, and index cards. I later added a whiteboard (now a chalkboard) into the mix.

What I found out was that my productivity and understanding of what I was working on didn’t decrease at all. Instead, it increased with my enjoyment. This is what initially prompted me to expand my ongoing research focus from digital reading to annotation, note-taking and writing as well.

One of the reasons why I’ve spent so many years looking at digital reading was because I felt that many of the ideas from print-based reading have been lost in the transition. We have gotten many of the basics right with our digital reading interfaces. Typography and resolution are much improved, for example. But our apps and devices rarely go beyond those basics and it’s rare to see any meaningful variations in the reading app genre.

My fountain pens and index cards made me realise that note-taking, esp. when you include annotation, shares many of the same problems, both in implementation, the lack of variation from the basics, and the lossy translation from print. Most importantly, they all tend to lack a sense of joy.

Hence, Colophon Cards. It might not end up being revolutionary but hopefully, with enough work, it’ll add some polish to the note-taking app genre.

(Next, what I learned about the various kinds of note-taking from talking to a bunch of people.)