Minimal note taking & task tracking as a software engineer

Note taking (and productivity as a whole) has become a much debated topic in recent years, it’s almost tribalistic in the way people advocate for their particular approach to organisation. At this point, I’ve tried them all: Notion, Obsidian, Apple Notes, even Evernote (sorry Evernote, you used to be good). They each had their benefits and drawbacks, but in the end, I gave up on each of them. I found them to either be too cumbersome, or too inflexible.

This lead me to devise my own system for note taking, which I’ve now been using for 4+ years. At this point, I feel it’s mature enough to document in the hope that others may find it useful.

Requirements

When creating this system, I had a few key tenets:

  1. Simplicity - I don’t want a million features, I want to take notes.
  2. Extensibility - I should be able to integrate the system with other tools as required.
  3. Searchability - I need to be able to find things at any point in the future.
  4. Portability - I don’t want to be locked into a proprietary format or piece of software.
  5. Enjoyment - If I don’t enjoy using it (strange concept for a note taking system I know), I won’t keep the habit.

What is it built with?

The million dollar question… Let’s start with the high tech stack:

Ok so I lied, not high tech at all. But that’s the point (see tenet 4 above). Fundamentally, the cornerstone for this system is my love of Vim. We’ll revisit this in a later blog post, but I prefer to operate my computer via the keyboard whenever I can. Other than Obsidian, none of the other options supported this.

At this point, I’ll direct your attention to the system itself: https://github.com/adam-c-fox/minimal-dev-journal

You’ll note 2 bash scripts, and a markdown file (see tenet 1):

  • new_week.sh - How you’ll interact with the system
  • latest.sh - A 1-line helper script
  • blank_day_entry.md - The format of each daily entry

How does it work?

At the beginning of each working week, you’ll run the new_week.sh script. After experimenting with individual days vs weeks for the contents of each markdown file, I found that moving tasks between days was something I did frequently, and individual markdown files for each day would result in working across many open files.

This very simple script prints the day and date for each weekday, and inserts one instance of blank_day_entry.md per day. You can put whatever you like in here (e.g. perhaps more like a scrum update: yesterday, today, blockers), but I found “TODAY” and “TOMORROW” were enough for me. “TODAY” houses the day’s running todo list. “TOMORROW” is used as a staging ground for unfinished tasks, or new ad-hoc requests that I know I won’t have time for today.

The final piece of the puzzle is the key. Based loosely on the bullet journal technique of using the bullet point to store metadata about the task, I developed a simple key for tasks. See this example entry for the most common ones:

#### Mon 23/09/2024

TODAY:
  - This is a completed task
  * This task is yet to be completed
  - Cool Task
    - These are some notes for the Cool Task
  X This task got cancelled
  - [13:00] This is a meeting I attended
    - With corresponding notes
    * And an action item that I will complete at some future time
  * [14:00] This is an upcoming meeting

TOMORROW:
  * This is a task that I did not complete today, and will complete tomorrow

Keying the tasks in this way helps the system be information and interface dense, you’re never poking around for a submenu to “tag” a todo with some random classification.

Because this system is really just a bucket full of timestamped markdown files, we can search the corpus quickly with a tool like ripgrep:

> rg dog
23_09_24.md
15:  * [09:00] Meeting with my dog

At this point I’m up to ~200 files, and ripgrep still returns almost instantly.

Backing up the data is just as easy, pick any file backup service. A cloud service like Dropbox would even provide this system with mobile support.

How do you use it?

Aside from the obvious (it’s just a todo list after all), I have one key mechanism that does help improve my productivity. Each morning, my first action of the day is to open this file, and do the following:

  1. Clean up the previous day. Make sure the entries reflect the true state of the task (done vs in-progress).
  2. Move unfinished tasks from yesterday into today
  3. Organise them into the desired order of completion
  4. Add any new items you can think of immediately
  5. Consult the calendar, add in today’s meetings
  6. Re-position the entries around the meetings, i.e. I’m going to try and finish this feature before my 2pm meeting (these aren’t hard boundaries, just initial thoughts, they’re often subject to change)
  7. Get Stuff Done!

I find spending these 5 minutes thinking through my tasks helps avoid a situation where I have to spend time deciding what to do, a disruption which greatly reduces your overall velocity.

Why does it stick?

It would be remiss of me not to acknowledge that this system probably works for me because it was designed by me. Someone who lives in the terminal, loves Vim, and is comfortable with taking ownership of the file management.

That disclaimer aside, and trying to be objective, here are some of the reasons I think I’m still using this after so long:

  • Vim - I promise this is the last time I’ll mention it (in this post), but it really is a dealbreaker for me. Spending the majority of the rest of my day in some program that supports these bindings, means I’m much slower editing text without them. It also increases the cost of context switching if I have to keep switching input modes. And because each line is an entry in the todo list, commands like dd (to cut the entire line) are immensely helpful (versus using something like VSCode).
  • Performance - I don’t need yet another electron wrapper eating several hundred megabytes of RAM to write text notes in.
  • Reduced cognitive load - As software engineers, we spend a lot of time learning new things. Programming languages, architecture paradigms, syntactic sugar… I don’t want to spend time learning a new note taking application when the one I like either gets a full facelift, or ceases to exist altogether.

Are you going to make any changes?

Apart from some quality of life improvements, probably not. The beauty is in the simplicity :)

But next up will be a slightly cleverer version of new_week.sh. If you start the week on a Tuesday (e.g. for a public holiday), I usually rename the file to be the Monday (for searchability), manually add an entry for the Monday, and remove the Saturday that was added on the end (the script is dumb and inserts 5 days no matter what).