An ode to note taking with markdown files

This is based off a sesh (think lightning talk, but... cooler?) I gave at Oxwash, where I am a frontend software engineer. I wanted to give an overview for how I take notes in pretty much every area of my life, including my job but also for holidays, notes from books I am reading, and for writing posts like this.

Over the past twelve months my thinking has converged towards the idea that plaintext files (like Markdown) are a great choice for note making and keeping. Please, let me explain why.

I'm not going to talk about any particular software in this post, just explaining why I think plaintext is cool. God I love the internet.

What do I want in notes ?

The entire argument I am about to make relies on a couple of assumptions. The first is that you want some kind of personal productivity or knowledge management infrastructure in your life. You might not want any, or you might be okay with the default Notes and Tasks apps on your phone. That's fine.

The second is that this is the kind of thing you can get down and nerdy about.

Now that I've weeded out anybody remotely cool, let's talk note taking and productivity.

No matter what tool I am using to take notes, I am trying to optimise for a couple of non-negotiable things:

  1. The speed of getting an idea out of my brain. My brain can get a little cluttered, and ideas can sometimes clamber over each other as they try to get out.
  2. The ability to find a note after I've written it. I don't care how it works, I can adapt, but normally at least one of the following things will stick around in my brain to let me find something:
    • A bit of the filename
    • A rough time when I made the note
    • A list of directories it's probably in
    • I remember that I mentioned the file in another file
  3. I am able to integrate my meta-work easily into my actual work, as:
    • A software engineer
    • Someone who writes blog posts that no one reads
    • Part of my ongoing professional development and research
    • Reading / reviewing / keeping notes on books
  4. A note can be deleted (or discarded) when I'm done with them, without impacting anything else.
  5. I want the reasonable ability to own my data and I don't want it to be in a proprietary format

Atomic vs. Ecosystem productivity tools

I've gone through a lot of productivity tools and techniques in the past ten-ish years, where I've gone from undergraduate, to doctorate student, to software engineer in small and large companies. Right now, plaintext, specifically markdown (.md), account for maybe 90% of my productivity and meta-work. I rarely find myself needing to move outside of them.

Previously, I flitted between two productivity ideals:

  1. Atomic tools where one job is done by one thing - task managers for TODOs, spreadsheets for data, notes for... notes. I have previously used apps like Bear (markdown-like notes), Google Sheets, and Todoist (task manager).
  2. Ecosystem tools where one tool should contain everything: TODO lists should be aware of personal budgets, should be linkable to meeting notes and product designs. Notion is the current Platonic ideal of this philosophy.

I found atomic tools difficult to manage in practice, because you have to figure out how to tie multiple disparate systems together. You've also got to learn how multiple tools think about data and workflows.

I didn't like ecosystem tools as much as I wanted to, because in practice they're trying to be a consumer-friendly operating system for information and workflows. As an engineer, I didn't like how ridged they are. Nor did I like how proprietary they are. I'm good to not put all of my valuable information onto a boat captained by an engineer out in San Fransisco who doesn't particularly want to resist the siren call of VC funding.

Plaintext isn't an atomic tool, because it can contain a variety of different kinds of information. Nor is it an ecosystem, because it can't (ergonomically) contain every kind of information. Previewing tables and images in markdown is... not particularly user friendly.

That said, plaintext notes are simple and accessible - every smart device I own can download files from the cloud, and has a way of editing them. Sure the editing experience is inconsistent, sharing external web pages or files into them is also a bit of nightmare, but the file format is present. And how much of success is just turning up?

Plaintext is kinda like Lego

The fact that plaintext is just text is a disadvantage. But plaintext still lets you put different kinds of information together in the same place. They're composable and combinable. One note can contain TODO lists, links to web pages, single-sentence thoughts, headings for structure in the document. That means I can have a file that represents a single day, a project, or a planned period of work - I don't have to divide everything off arbitrarily. And I can do this differently for every note.

You can also link things together at the file level. By naming convention or location of the file, or just calling a file out - things can link together easily.

A single plaintext note can easily support most things from infancy to adolescence. Some things, like data-heavy lists or tables, have practically no room to grow (at least not without software-based enhancements). Others, like a collection of notes and quotes from books I am reading, are able to expand almost infinitely. Most things, sit somewhere in the middle.

Importantly, when something outgrows the medium of a plaintext document I am able to link the two. Even if this only a one way link, from markdown to a URL, or a copy-paste job from an e-mail. Is it perfect? No, but it's just plaintext. It's open source, it's human readable, and it makes sense to me. The computer doesn't need to understand everything I do and say, it just needs to remember what I say and let me do the figuring out.

Notes are a tool that serve you

Digital note taking brings together two very opinionated groups: people who think about software or digital systems, and people who work in research or communication. It is easy to find a lot of zealous doctrine online about what makes "good" notes.

Take their ideas as inspiration. Or ignore them. They're not going to hunt you down to ask why you don't implement their note template, and if they do they're probably weak from sunlight deficiency and lack of social awareness.

If you're serious about creating and then maintaining a habit, it has to offer some clear benefit to your life. Following an additional set of rules and guidelines for their own sake may work for some people who love following rules. You do not serve the monolith of your notes archive - it serves you.

If your notes are long and sprawling, that's fine. If they're short and clipped, cool.

See other articles