Stopping (human) memory leaks

November 9, 2020

As your workload increases, you might start thinking:

  • "I did this once, but I don't remember how..."
  • "What were the options to this command again?"
  • "What did I do this month? Time sure flies..."
  • "I'm flooded with docs, posts, and meetings, and yet I don't feel like I'm retaining anything!"

I've certainly been there myself. I started at Facebook in spring 2020. The combination of a new job, pandemic uncertainty, and lockdown isolation - all made it difficult to concentrate. To help myself focus, I took stream-of-consciousness notes, adding more details and structure over time. Eventually, I arrived at a process I'm going to share with you below.

What to write

Each task is written up in a separate, plain text, Markdown-formatted file. The files are stored in a single directory, automatically backed up to Dropbox.

I chose this combination because text files are searchable using tried-and-tested command line tools. Furthermore, Markdown provides a sufficient amount of formatting, handles code snippets nicely, and is highly portable.

In the template below, I usually edit the "Steps" section, expanding "Implement/Fix" into a detailed action plan. In the steps, I include a stream-of-consciousness log of what I'm doing, along with code snippets, command-line invocations, extracts from stack traces etc.

# (task ID)

Tags: #task

* Task ID: (task ID)
* PoC: (my email)
    * other interested people: (emails)
* When: #{date:YYYY-MM}
* Status: #status-todo | #status-open | #status-blocked | #status-review | #status-release | #status-land

## Thanks

* (email)

## Decisions / Choices

* (choice)
    * stream of consciousness list of reasons

## Steps

* [ ] Summarise the task
* [ ] Write test plan
* [ ] Implement/Fix
* [ ] Test
* [ ] Get review
* [ ] Release
* [ ] Communicate (announce, thank, etc)

### Task summary
...

### Test plan
...

### Implementation
...

### Test results
...

Re-read your notes

The initial value of task notes is that they provide a journal, grounding you in what you're currently doing, and reminding you where you left off (context-switching can completely wipe your memory).

You can also extract value from a collection of notes on finished tasks. Here are some ideas of what files to search for:

  • backlog: list files that contain #status-open or #status-todo
  • work done this month: list files that contain #status-done and #YYYY-MM for the given year/month
  • feedback for a teammate: list files that contain their name and #YYYY-MM for every month you want to cover in feedback
  • re/connect with a someone: list files that contain their name and sort them by last modified to find out when you worked together last and on what
    • if you use a wiki-system, you can create a page named after this person, and link every instance of collaboration to this page
  • tool documentation: files that contain the name of the tool
    • if you grep and dump the results into a single file, you can create a file with personalised tips about a tool
    • if you use a wiki-system, you can create a page named after the tool, and link every instance of tool name to this page

Make your own template

You'll want to evolve your own task template slowly. In my experience, attempting to start big results in procrastination, because the amount of bookkeeping can look overwhelming.

What might you include in your own task template? Here are some ideas, split into five Ws (and a H):

When

  • When did you work on the task?
    • you could use a monthly tag #YYYY-MM or w/c (week commencing) tag #wc-YYYY-MM-DD or a combination
  • What is the deadline?

Who

  • Who filed the task?
  • Who knows the most about this area?
  • Who needs to be updated about the task progress?
  • Who helped you during the task?
  • Is there a single "point of contact" person for this task or project?

What

  • What is the result supposed to look like? Can you summarise it in your own words?
  • What tools have you used?
  • What errors were reported?
  • What are the relevant stdout snippets?

Why

  • What is the purpose of this task?
  • What are the decisions or choices that you made during this task? What options have you considered? Why did you settle on this one? Did you change your mind later?

How

  • How can you confirm that you've successfully implemented what you set out to have? (Write the test plan ahead of time.)
  • What's your development / fix plan, in as great detail as you only can?

Where

  • What files, repositories, databases etc have you touched?
  • What permissions do you need?

Appendix: editors

I started out with Sublime Text and markdown extended plugin.

However, this note-taking approach is highly compatible with wiki-systems (Roam-inspired editors and extensions), such as:

Tags: productivity grok