The Note-Taking Setup That Actually Works for Developers

Developer note-taking fails for a reason that note-taking advice rarely addresses: the thing a developer needs to remember is not information, it is decisions.

"Why is this queue consumer idempotent" is worth remembering. "The queue consumer processes messages" is in the code and reading it again takes four seconds.

Most note systems are optimised for capturing information. A developer's system should be optimised for capturing reasoning, because reasoning is the part that is not in the repository.

What developers actually need to capture

Four categories, and they belong in four different places.

Decisions and their context. Why we chose Postgres over DynamoDB, what we rejected and why. This is the highest-value note and the one most often skipped. Six months later the code shows what you built and nothing shows why.

Commands you had to look up. The exact ffmpeg flag, the kubectl incantation, the SSH tunnel syntax. These are not knowledge, they are muscle memory aids, and they should be one keystroke away.

Debugging trails. The error message, what you tried, what actually fixed it. Search engines will find the error; they will not find your stack trace plus your specific environment.

Meeting outcomes that turned into work. Not the meeting, the decisions and who owns them. This usually belongs in your issue tracker, not your notes.

Note what is not on the list: code snippets. More on that below.

Why code in notes is a trap

Copying a function into your notes feels productive and is actively harmful, because the copy immediately begins to rot. In three months it will be subtly wrong, you will paste it, and it will compile and behave differently from the version in the repo.

The alternatives, in order of preference:

1. Link to the commit. A permalink to the file at a specific SHA never lies.
2. Link to the repository path. Fine for stable code, breaks when files move.
3. Write the pattern, not the code. "Retry with exponential backoff, jittered, max 5 attempts, respect Retry-After" is more durable than any implementation.

If you genuinely need snippets, keep them in a ~/snippets directory under version control, not in your notes app. Then they are code, tested and versioned, rather than text pretending to be code.

The setup

Obsidian for decisions and debugging trails. Plain Markdown, local, fast, searchable, and yours. The properties that matter here are: it opens instantly, it works offline, and the files will outlive the app.

Structure: one folder, flat, no elaborate hierarchy. Filenames that are sentences, because you will search by remembering the sentence. why-we-dropped-redis.md is findable. 2026-03-14.md is not.

Raycast for commands. A snippet or a quicklink for anything you look up more than twice. This is the highest-return five minutes in this entire setup, because it converts a context switch into a keystroke.

Your issue tracker for work. Linear, Jira, GitHub Issues, whatever you use. Decisions that affect a ticket go in the ticket. Notes are for what has no ticket.

The repository for everything else. Architecture decisions belong in docs/adr/ or a README, not in your personal notes, because the next developer needs them and will never read your vault.

The one habit that makes it work

Write the note at the moment of resolution, in one paragraph, before you move to the next task.

The pattern: you spent two hours on a bug. You fixed it. Before you close the tab, write three lines: what the symptom was, what the cause was, what fixed it.

This takes ninety seconds and it is the difference between a note system that compounds and one that dies. The reason most note systems die is not the tool, it is that people plan to write things up later, and later never comes because the context has evaporated.

What to skip

A second brain. The framing is aspirational and the practice is a hobby. You need a searchable record of decisions, not a knowledge graph.

Elaborate tagging. Tags work when the vocabulary is stable. Yours will not be, and you will end up with #db, #database, and #databases as three separate tags. Search the text instead.

Daily notes. Useful for some people, useless for most developers, because the unit of work is a task, not a day. If you want a log, log per task in the tracker.

Syncing everything. Your notes should sync; your code should be in Git. Do not try to make one tool do both.

The test

A good developer note system passes one test: six months from now, can you answer "why is this like this" in under a minute?

If yes, the system works regardless of which app you chose. If no, the problem is not the app, it is that nobody wrote down the reasoning at the moment it existed.