On Taking Short Notes


A good note-taking tool has the following qualities:

  1. It must be text-based.
  2. It must have a responsive UI.
  3. It must be easily to search.
  4. It should work with Markdown.

The first tool I found to cover these bases was Notational Velocity and later, Brett Terpstra’s excellent additions in nvAlt.

Screenshot of Notational Velocity.

Screenshot of Notational Velocity.

I used both for over a decade to store short snippets of infrequently used information and to jog my memory. They were both fantastic tools that showed me what I needed in a note-taking tool.

Lately I started building a note-taking app for myself, which has me feeling a bit nostalgic for these kinds of tools. I pulled a few examples from notes I created in NV long ago to highlight what sorts of things I typically kept track of.

Case #1: Saving a Snippet

Here’s one I made with flags I must have used with ack at some point. It is similar to a gist (but kept locally in my home directory). I don’t use ack anymore, but there was a time when using ‘ack’ felt like a superpower.

ackrc.rtf / Oct 15, 2009


That’s it. That’s the note. I have many more like this. They are composed of nothing more than a semi-descriptive filename and something as light as a single query, a reminder of how to use FFmpeg to strip audio, or common Kubernetes commands.

Case #2: Replacing the Post-It

Here’s a more recent example.

I had an old 2011 MBP, which I affectionally named my “Zombie MacBook” because it broke in awful ways before I brought it back to life. At the time, it was an eight-year-old MacBook with a storied history, having traveled with me for years across three continents.

One of the final nails in the coffin for this machine came with its inability to boot after any system update was applied and, in some cases, from sleep. There were several recovery steps involved, but one of the hardest to remember was setting an NVRAM parameter once in recovery mode (I still wince at the memory).

I kept a post-it note on the machine with the following code for years. And once I lost the post-it, I created this note for myself in nvAlt.

nvram+macbook pro 2011.md (August 8, 2020)

sudo nvram fa4ce28d-b62f-4c99-9cc3-6815686e30f9:gpu-power-prefs=%01%00%00%00

I never kept passwords in NV, but I did keep URLs for test environments or curl commands to perform a gut-check on some internal system. Anything better than searching a shared wiki, Google Doc or hunting for an email.

Case #3: Meeting Details

This one is related to a technical interview question I would give prospective candidates. Like shorthand, each line here is a detail presented as part of a larger problem.

architecture design interview.md (April 23, 2015)

- 100k RPM (read), < 10ms rsp
- 50 RPM (write), <2kms rsp

This is not an interview template, but at the time I wrote it down, it was pertinent to me somehow. Could you imagine how nonsensical this would have looked on a google doc or in a shared wiki? But in my head I had all the details pinned down– I simply needed to remember a few numbers.

Case #4 Random Bits of Life

Have you ever had to reset the code on an old Audi A4? The instructions are maddeningly complex. It’s crazy that people used to do this (it’s also crazy to think people used to steal car stereos that often).

Audi radio code for stereo.md (Aug 14, 2011)

**Code: 9999**

1. Turn on
2. Press FM2 + RDS and hold on till "1000" appears
3. Use presets 1..4 to enter 4 digit code.
  - Preset button 1 corresponds to the first digit
  - preset button 2 corresponds to the second digit, etc.
  - Each press of the button increments the number by 1.
4. Once the code is correct, press FM2 + RDS buttons simultaneously and hold until
   the word SAFE appears.

I Don’t Need Another Website For This

I never understood why others prefer heavyweight note-taking tools on one end of the spectrum or “distraction-free” experiences on the other.

If the heavyweight options are too distracting, the answer is not to reduce note-taking to a single text box. That just makes discovery harder, and puts more of a mental burden on the user to remember how to use the tool.

Removing distractions works well for long-form writing, but most notes I write are miniature, personal reminders. They are the tools I wield when confronted with a task that requires quick recall. And I don’t mind a bit of guidance to lead me from feeling like I need a piece of information, to finding what I need.

An excellent note-taking tool is an extension of your thought process. It should recognize that human beings do not think in paragraphs, and we rarely know what we need until we’ve searched a few times for it.

The best tool should reflect those realities.

(cover photo screenshot of Notational Velocity)