How to Take Programming Notes

Most programming notes are worthless for a specific reason: they restate documentation. A note explaining what git rebase does is a worse version of a manual page that is one search away and always current. If a note competes with the docs, the docs win.

The notes that pay are the ones nothing else contains. There are four kinds.

1. TILs — the thing you just figured out

The highest-value note in software is the small, awkward fix that took forty minutes and is nearly unsearchable. The Postgres flag. The reason the Docker build only fails on CI. The two-line incantation that makes the certificate error go away.

Simon Willison has published hundreds of these as public "Today I Learned" notes, and describes them as the most liberating form of writing: I just figured this out, here are my notes. Most take under ten minutes to write. The format is minimal and worth copying exactly:

• Title states the problem, not the topic. "Fixing SSL: CERTIFICATE_VERIFY_FAILED on macOS Python" — not "Python SSL."
• The error message, verbatim. This is the single most useful line in the note, because it is what future-you will search for. Paste it in full, including the parts that look like noise.
• The fix, as a command you can copy.
• One line of why, if you know it. If you don't, say that. "No idea why this works" is an honest and useful note.

Write it while it is still annoying. An hour later you will believe it was obvious.

2. Decisions — the ones that will look wrong later

Code records what you did. Comments record how it works. Nothing in the repository records why you chose it over the other thing, and that is the question every future reader — including you — will actually have.

A decision note is four lines: what we chose, what we rejected, the constraint that decided it, and the date. Teams formalise this as an architecture decision record checked into the repo, which is the right home for anything that affects other people. Personal decisions can live in your notes.

The value shows up when a constraint expires. "Chose the slower approach because the client's server was stuck on Node 16" is the difference between confidently deleting a workaround and being scared of it for three years. This is exactly the class of note that should never be deleted — you cannot reconstruct it from the code.

3. Debugging logs — written while you're stuck

Keeping a running log during a hard bug feels like overhead and is the fastest way out of one. Write what you tried, what you expected, what actually happened. Three effects, all real:

• It stops you retrying the same thing at attempt eleven, which everyone does.
• Explaining the problem in writing solves a surprising share of bugs outright — the written form of rubber duck debugging.
• It frees the working memory you were spending on holding six hypotheses at once, which is the resource you are actually short of.

Delete it when the bug is fixed, keeping only the finding. The log is scaffolding; the TIL is the building. Interstitial journaling is the same technique applied to a whole working day.

4. Project context — how to get back in

The note that saves the most time in practice is the least intellectual one: how to run this thing. Setup steps, the env vars nobody documented, which service must be started first, the port, the test account, where the logs are. Write it the first time you onboard yourself, because that is the only moment you can see what is not obvious.

Keep it in the repo if it is about the project, and in your notes only if it is about your machine.

What not to write

• Syntax you can look up. Language reference notes go stale and lose to search.
• Tutorial transcripts. Copying a course into notes produces the feeling of learning and none of it. The only version that works is writing from memory afterwards — active recall applied to code, or better, building something small without the tutorial open.
• Code you did not run. A snippet you copied and never executed is a claim, not a note.
• Anything with a secret in it. API keys, tokens, connection strings with passwords. Your notes are probably synced through someone else's cloud and are almost certainly not in your threat model. Use a secrets manager.

Where to keep them

The main axis is whether the note travels with the code or with you.

For the personal half, the practical requirements are narrow: fast full-text search, code blocks that do not mangle whitespace, and plain files if you want them readable in a decade. Markdown for notes covers the format argument, and best notes app for developers covers the tools. Public TILs have an extra benefit worth mentioning: publishing forces the note to be legible, and legible notes get reread.

The one habit that matters more than the format: write the note when it is still annoying, not when it is interesting. More guides in how to take notes.