Mounting obligations

I work as a software engineer at Gusto. On a typical day, many things are going on in my head:

• I am reviewing a PR, and I want to comment about a programming pattern, but I can’t find the reference. It was from one article I read a while ago. It must be buried in one of my notes.
• Received a Slack alert about the peer feedback I committed to writing down. I need to message my manager and ask for an extension.
• There are 30 minutes left for the next pairing session. I took a brief look at the tech spec, and had some questions. Should I comment on it? What if the doc addresses the concern in later sections? Let me make a mental note to go through the spec again.
• What about that issue CX team was asking about? A timeout error happened because the Rails ActiveRecord destroy caused a cascaded delete and it could take a long time depending on the associations. Did we arrive at a solution? Let me follow up on Slack.
• Github published an article about their MySQL scaling challenges. I want to bring it up in the #engineering channel, but haven’t got the time to word it properly in Gusto’s context.
• Wait, the new landing page banner we launched last week looks off on Safari v15.1. Okay, add a Reminder item for myself for double-checking.
• …

As a developer, I have to juggle the information among different levels of products, systems, processes, and people.

Each obligation, even if it seems small, requires my brain to retain some information, in order to make quality decisions about what’s next.

When I switch contexts, my brain is not willing to let go of all the information. It seems that my subconsciousness figures out that I would need it later, and if I let go, I may lose it forever, so it decides to hang on to it.

These small obligations start to clog up my brain. Soon I find it hard to take in new information because my working memory is overloaded. I start to feel overwhelmed, demotivated, and even lost. It reaches a point where I admit there is no way I can keep everything in my head.

Apps ≠ Solutions

When working in a team setup, I have all these tools that store information: Slack / Google Doc / Jira / Confluence / Apple Notes / Stickies / Notion / Evernote, etc.

Each tool creates a virtual space to host information, and it seems appealing in its own way. Examples:

• Once I made it a routine to send myself Slack messages with day planning notes and end-of-day updates. It worked fine until I found I could not edit past messages, or when I needed to access Slack offline.
• I also tried a private Google Doc / Confluence / Notion / Evernote document. But when there is a need to export to a different format, or I want to do offline editing and searching, I hit a wall.

All the commercial tools come with their own limitations. While working around the limitations, I form the editing habits that apply to the specific tool only, which increases this kind of vendor lock-in.

Later I realize this: Team knowledge management has different requirements than individuals. Faced with the mounting obligations, and the reality of having to switch between these tools, it just does not feel like a fit to use a team oriented tool for personal use entirely.

One plaintext file to rule them all

After years of using other tools and trying to stay organized, I found using one single plaintext file is the simplest, and most effective device to act as my second brain.

I name my plaintext file wm.txt. wm is short for working memory. It borrows the concept from Cal Newport.

I put the file to the Desktop folder. You can put it any places where it's most visible to you. Also, I keep the wm.txt editor window open all the time. With that, I have my second brain with me.

Offload! Offload! Offload!

The rule is simple: Whenever I’m about to make a context switch, I jot down the thoughts on my brain, whatever they are.

The content may not make sense to anyone else but me. It was meant for individual to keep a brain dump. As long as the content serves as a reminder of some early thought, and my future brain can pick up quickly, it is good enough.

wm.txt becomes my go-to place for any information in my brain. It offloads the storage to this container.

Offloading comes with unexpected benefits. During the offloading phase, I am forced to distill my thoughts into text. It often produces a strange side effect: I clarify my thinking, guide the brain to produce something that is quickly digest-able (by me), and enhance my understanding and memory of the information.

After some practice, nearly all my knowledge work happens in this text file. For example, I will craft a long form text response on my text file first, and the paste into Slack.

And I’m free from vendor lock-ins. This text file is universally readable and grok-able format. As an extreme example, I can keep the same workflow on a Windows 95 desktop without Internet access, as long as it has Notepad.

wm.txt is the one tool to rule them all. All other tools should bow.

Organize by date & task items

As the brain dump accumulates, the file becomes long, and I had to be more organized. Again, I adhere by the simplicity principle, and choose to use organize the notes by date.

I usually start the day by opening Google calendar, and copying the important meetings as the first items in the list.

Then I will go over the previous day’s items and pick up any loose threads I need to follow up.

The definition of “item” is loose: It can be a task, a calendar item like a meeting, a research topic, etc.

As the day goes on, I add notes under the item. There is no restriction on what notes. It is basically free-form text.

The point is not to overthink. As long as I feel it is worth writing down, or worth reminding my future self about, I will dump there.

One benefit of organizing things this way is I can search the file to find the info I need. Prof. Jeff Huang uses a similar workflow to organize his academic obligations.

By trial and error, I get better at writing info with the personal vocabulary that is mnemonic and searchable. For example, I wanted to find the my 1-on-1 notes with manager by searching “1:1”, but nothing showed up. That’s because the item was written as “meeting with J”. When I eventually found it, I reworded the item as “1:1 with J”, so next time I could find it.

Long term memory management

You can imagine the wm.txt file keeps growing as days go by and I add more notes.

A long file is not an issue by itself. TextEdit, or any text editor can handle a large number of lines of text before I hit a limit and experience slowness. Mine grew to 200K lines for once and it works fine.

The benefit of keeping everything in one file is the same old simplicity. For example, I can search by date and found out what happened then.

If you are a verbose note taker, or likes to copy large code snippet there, you can always back it up and start a new wm.txt from scratch.

However, sometimes I kept searching the same keyword and going back to some old task notes, where they contains reference solution and code snippets.

wm.txt may not be best storage for this kind of evergreen notes, because it is hard to search and tag. Also, it’s not easy to update and draw connections among notes.

There are other approaches or systems that solve the long term knowledge management problem, such as Zettelkasten, or Roam.

This post is about working memory management. I plan to write a separate post about how I manage my evergreen notes. Stay tuned!

Bonus:wm.org and Org-mode

Since I use Emacs, I adopted Org mode not long ago. Org-mode aligns well with the plaintext approach. The difference is mainly that org-mode file comes with a set of outline structure (with the asterisks) and source code snippet support.

With org-mode, I renamed my wm.txt to wm.org, open it on Emacs, and it has better indentation and syntax highlighting. For example:

In terms of the content, I write the same notes as before. There is no workflow changes.

*.org files are just plaintext files with minimal structure. I can open my wm.org in TextEdit, and it is still legible:

Another change is I put my wm.org under Git control. Because it is a plaintext file, it is easy to diff. With Git, I could relax and edit my past notes without fear of losing any editing history.

However, both org-mode and Git version control are optional for the plaintext workflow. They are personal preferences. You can keep using a wm.txt file and enjoy its simplicity and maximum flexibility.

Summary

After using a plaintext file as a second brain for nearly two years, I develop trust on this simple system. I offload all my thinking to the plaintext file, and move on to a different context, rest assured that I won’t lose any information, and pick up the thinking quickly when I need to.

This plaintext file frees my brain from retaining information. Development related tasks, like debugging, feature development, tech spec writing, all end up as items in my second brain, where I take notes, refine, ponder and conquer!