Last week I spent 45 minutes debugging a Docker networking issue. The container couldn't reach an external service. I tried everything. Finally found the solution buried in a Stack Overflow comment: the DNS resolver was wrong, needed to add a specific flag to docker-compose.

Sound familiar? Here's the worst part: I'd solved this exact issue eight months ago. I remember it now. I just didn't remember it then when I needed it.

Our brains are terrible at storing the kind of information software development requires. Exact syntax. Specific command flags. The weird workaround for that one library bug. We solve problems, and then we forget how we solved them. Then we solve them again. It's exhausting and wasteful.

The solution is stupidly simple: write things down. Not in a fancy app. Not in a complicated system. Just... write them down somewhere you can search later.

The Problem With Our Memory

Human memory evolved for recognizing faces and remembering where predators hide. It did not evolve for remembering that git rebase has a different flag order than git merge, or that PostgreSQL uses single quotes for strings but MySQL accepts double quotes.

We pretend we'll remember. We tell ourselves "I'll remember this, it's important." We never do. A week later we're googling the same error message, clicking through the same Stack Overflow threads, having the same "oh right, it was that" moment.

The senior developers I respect most aren't the ones with encyclopedic memory. They're the ones with good notes. They've externalized their memory into a system that doesn't forget.

What to Write Down

Not everything. That's a trap. If you try to document every function call, you'll burn out and stop taking notes entirely.

I write down things that pass the "30 minute rule": if I spent more than 30 minutes solving something, it gets documented. That's the threshold where forgetting the solution actually costs significant time.

A few categories I focus on:

Error messages and their fixes. These are gold. When you see "FATAL ERROR: Ineffective mark-compacts near heap limit" for the second time, you want to immediately know "increase Node memory limit" without any searching. 

# Node heap error

## The problem
Build crashes with: FATAL ERROR: Ineffective mark-compacts near heap limit

## The fix
Node has a default ~1.5GB memory limit.
Increase it: export NODE_OPTIONS="--max-old-space-size=4096"

Or in package.json:
"scripts": {
  "build": "NODE_OPTIONS='--max-old-space-size=4096' webpack"
}

## Notes
Usually happens in CI where machines have less RAM than local dev.
First hit this in May 2025 on the reporting service.

Workarounds for library bugs. Every dependency has quirks. That weird thing where you have to call an init function twice, or the config option that's documented wrong - write it down before you forget.

Commands you use rarely. I can never remember the tar extraction flags. Or how to do a git bisect. Or the exact psql command to restore a backup. These live in my notes now.

Where to Put It

I've tried Notion, Obsidian, Evernote, Bear, plain text files. The tool doesn't matter as much as picking one and sticking with it.

My only strong opinion: use plain text formats. Markdown specifically. Here's why: I've lost notes to apps that shut down or changed their format. Text files still work. They worked 20 years ago, they'll work 20 years from now. I can open them in any editor, search them with grep, version them in git.

Whatever you choose, it needs good search. The whole point is finding things quickly. If you can't search your notes in under 10 seconds, the system is broken.

I keep mine in a single folder synced across machines. Nothing fancy. One folder called "dev-notes" with markdown files. Works for me.

Project-Specific Notes

Every project I work on gets a NOTES.md file in the root (gitignored). This is different from documentation - it's my personal scratchpad for that project.

Stuff that goes here: database credentials for the local environment (yes I know, don't @ me), that one curl command for testing the webhook, why the test suite needs a specific environment variable, what the previous developer meant by that cryptic comment in the config file. 

# Project notes - customer-portal

## Local setup quirks
- Need to start Redis before the worker: `redis-server`
- The seed data takes 5 minutes, don't interrupt it
- Local SSL certs expire monthly, regenerate with scripts/gen-certs.sh

## API gotchas
- The /users endpoint returns 404 for soft-deleted users (not 200 with a flag)
- Rate limit is 100/minute but errors don't count toward it
- Auth tokens expire after 1 hour even though the docs say 2

## WTF moments
- Don't touch the PaymentLegacy class. I tried once. Three days lost.
- The "analytics" database is actually used for feature flags (legacy naming)

When I come back to a project after months away, this file saves me hours of rediscovery.

The Capture Problem

The hardest part isn't organizing notes. It's writing them in the first place. You solve a problem, you're tired, you want to move on. Writing a note feels like extra work.

Two things help me. First, I keep the notes file open while I work. It's always one tab away. Low friction matters.

Second, I write notes ugly. No formatting, no complete sentences, just enough to trigger my memory later. I can clean it up later if I need to (I usually don't). 

docker compose network issue - containers cant reach external services
fix: add dns setting to compose file
dns:
  - 8.8.8.8
  - 8.8.4.4
was using wrong resolver, company vpn thing probably

That's ugly but searchable. If I search "docker dns" or "compose network" I'll find it. Good enough.

Actually Using Your Notes

Notes you never read are useless. Build the habit of checking your notes before googling.

When I hit an error message, my flow is: search my notes → search our team wiki → google. Usually my notes are faster than google because they're already filtered to stuff that's actually worked for me, in my environment, with my setup.

Once a week I spend 15 minutes reviewing recent notes. Not studying them, just skimming. This does something to help retention - apparently it's called "spaced repetition" and there's science behind it. I don't really care about the science, I just know it helps me remember more.

When Notes Become Documentation

Sometimes a personal note turns out to be useful for others. That weird setup step that tripped you up will trip up the next person too.

When I notice a note that would help my team, I turn it into actual documentation. Not all notes - just the ones that solve problems others will definitely hit. The README, the wiki, wherever your team keeps shared knowledge.

Personal notes are for you. Documentation is for everyone. Keep them separate but let good notes graduate when they're ready.

Start Now

You don't need a perfect system. You need any system. A text file on your desktop. A private GitHub repo. A physical notebook. Whatever you'll actually use.

Next time you solve a problem that took more than 30 minutes, write it down. The error message. What you tried. What actually worked. Future you will be grateful.

I've been doing this for about four years now. My notes folder has maybe 200 files. Some I reference weekly. Some I haven't opened in years. But every time I'm stuck and search my notes and find the answer in 30 seconds, I'm reminded why this matters.

Back to Developer Productivity

Back to Home