I have a folder on my laptop called notes-final-v2. Inside it is another folder called old. Inside that, a file named IMPORTANT.md that contains a single Docker command, no context, and a link to a Stack Overflow answer that's since been deleted.
That folder was my personal knowledge base for about three years. If you're a developer, I'd bet you have something like it. Maybe it's a Notion workspace with 40 empty pages, a pile of GitHub stars, or a Slack channel you DM yourself in.
I've rebuilt my setup a few times now. This is what I'd tell someone starting one today, mostly so they skip my mistakes.
Decide what the knowledge base is for
Most dev notes fail because they try to be three things at once: a snippet library, a journal and a reading list. Those have different jobs.
A snippet library answers "how do I do X again?" You search it when you're stuck. A journal records what you did and why, which is gold when you're debugging something six months later. A reading list is stuff you haven't processed yet.
The first two are worth keeping. The third one is where good intentions go to rot, and I'll come back to it.
Plain text wins, mostly
I've tried Notion, Obsidian, Logseq, Apple Notes and a private GitHub repo full of markdown. The one I've stuck with longest is the boring one: markdown files in a repo, opened in the same editor I write code in.
The reasons are practical. I can grep it. It lives next to my terminal, so writing a note takes ten seconds instead of a context switch. It's version controlled, so I can see when I learned something. And if a tool shuts down, my notes don't go with it.
Obsidian is a good choice if you want the same markdown files with backlinks and a nicer UI on top. Notion is great for team docs. For personal dev notes, I'd pick whatever lets you write a note without leaving your editor.
Write TIL notes, not tutorials
The format that changed things for me was the "Today I Learned" note, popularized by Josh Branchaud's til repo on GitHub, which has collected well over a thousand short notes since 2015.
A TIL note is small. One problem, one fix, a sentence on why. For example:
# git: undo the last commit but keep the changes
git reset --soft HEAD~1
Changes stay staged. Use --mixed (the default) to unstage them too.
Found this after committing to main instead of my branch.
That last line matters more than it looks. The context is what makes the note findable later, because you'll remember the situation before you remember the command.
I keep one folder per topic (git/, postgres/, react/, aws/) and a file per note. No tags, no nested hierarchy. When a folder gets past 30 or so files I split it.
Search beats structure
I used to spend Sunday afternoons reorganizing my notes. That was procrastination. What actually helps is making notes easy to find with a dumb search.
A few habits that make rg (ripgrep) do the work:
- Put the error message verbatim in the note when the note is about an error. You'll paste that same message into search later.
- Name files after the question, like
postgres/why-is-my-index-not-used.md. - Write the tool and version when it matters. "Next.js 14 app router" saves you from applying a fix that only worked in the pages router.
I have a shell alias, n, that runs ripgrep over the notes folder and pipes it into fzf. Most lookups take under five seconds.
The reading list problem
Now the bad news. Everything above works for things you've already figured out. It does nothing for the 200 tabs, talks, podcasts and blog posts you saved because they looked useful.
My reading list used to be a markdown file called later.md. It grew to around 400 links. I processed maybe one in twenty. The rest sat there making me feel vaguely guilty, and the handful I did read I forgot within a couple of weeks because I never looked at them again.
Two things fixed it, partly.
The first was a rule: a link only stays in the reading list for two weeks. If I haven't read it by then, it gets deleted. If it was important, it'll come back around.
The second was building something for the stuff I actually do consume. I ended up making Recl because I wanted the saved videos, reels, podcasts and articles to go somewhere other than a graveyard. You save a link, it writes a summary, sorts it into a topic, and then uses spaced repetition to bring the main points back to you over the following days and weeks. That covers the part my markdown repo is bad at, which is remembering things I didn't write down myself.
I still keep the TIL repo. They do different jobs. The repo holds things I've solved. Recl holds things I've learned from other people and would otherwise forget.
Review, a little, on a schedule
The difference between a knowledge base and an archive is whether anything ever comes back out. Once a week, usually Friday afternoon, I spend ten minutes skimming the notes I added that week. Sometimes I merge two into one. Sometimes I realize a note was wrong and fix it. Mostly I just reread them, which is enough to make them stick a bit longer.
If you want to go further, spaced repetition is the proven way to do it. I wrote about implementing the SM-2 algorithm in JavaScript if you'd like to see how the scheduling works.
Start smaller than you think
If you're starting from nothing, make a repo called til, add a folder for the language you use most, and write one note today about something you looked up. Tomorrow, write another. Don't design a system first.
In a month you'll have 20 or 30 notes that are actually yours. And the next time you hit that weird Docker error, you might find the answer in your own words instead of on page three of a search.
I'm Spartan Rich, and I build Recl, an AI learning app that saves your videos, reels, podcasts and articles, summarizes them, and uses spaced repetition so you remember what you learned.
Top comments (0)