I've tried everything. Confluence wikis that became graveyards. Notion databases so elaborate I'd spend more time organizing than shipping. Plain text files scattered across three machines. Bookmarks folders I haven't opened since 2021.
The problem wasn't the tools — it was that I kept treating note-taking like architecture: design first, populate later. Developers love systems. We'll happily spend a weekend building the perfect folder structure for notes we'll never write.
What actually worked was simpler and less elegant. Here's the setup I've been running for 18 months, why it holds together, and the specific habits that keep it alive.
Why Most Developer Knowledge Systems Collapse
The pattern is predictable. You start enthusiastic, dump everything into the system for two weeks, then stop opening it entirely. Six months later you rebuild it from scratch.
The root cause is usually one of three things: the system requires too much friction to capture, retrieval is slow enough that you just Google instead, or the structure was designed for an imagined future self who takes better notes than you actually do.
Developer knowledge has specific properties that make generic PKM advice bad. You need to store code snippets with syntax, link documentation to projects, track decisions that made sense three months ago but look insane today, and find things while you're mid-problem with no patience for nested menus.
The setup that works respects these constraints instead of fighting them.
The Two-Tool Split: Obsidian for Thinking, Notion for Reference
I use Obsidian and Notion for different jobs, and the distinction matters.
Obsidian is where thinking happens. Daily notes, project scratch pads, decision logs, half-formed ideas about architecture. It's local, fast, and Markdown-native. I can dump a code snippet in three seconds without reaching for a mouse. The graph view is genuinely useful for surfacing connections between projects — I found an old auth pattern I'd forgotten about while debugging a completely unrelated OAuth issue, just because the graph showed a link.
Notion is the reference layer. Tech stack documentation, client onboarding templates, API keys structure (not the keys — the structure), freelance contract clauses, recurring checklists. Notion is slower and requires a browser, but it's shareable and handles structured data better than Obsidian.
The rule I follow: if I'm writing to think, it goes in Obsidian. If I'm writing to store something I'll look up later, it goes in Notion. When in doubt, Obsidian first — I can always migrate a note later, but forcing yourself to open Notion mid-flow is how capture habits die.
The Folder Structure That Actually Holds
Here's the Obsidian vault structure I've converged on after many rebuilds:
/inbox — unprocessed captures, cleared weekly
/projects — one folder per active project
/areas — ongoing responsibilities (client work, open source, learning)
/resources — reference material I might need again
/archive — dead projects, old notes, nothing deleted
/daily — daily notes, auto-named by date
This is a modified PARA system. The critical piece is the inbox. Everything goes there first. When I'm mid-debug and I find a Stack Overflow answer that actually explains why something works, I paste the relevant bit in the inbox. I don't think about where it belongs. That decision happens during weekly review, not during work.
The archive folder is non-negotiable. Never delete — just archive. I've gone back to notes from three years ago more times than I expected, especially for client projects that resurrected.
Code Snippets: The Part Everyone Gets Wrong
Most developers either store snippets in their IDE snippet manager (siloed, hard to search) or in a random Notion page (buried, forgotten).
My approach: snippets live in Obsidian, tagged by language and use case, with context.
The context is the part everyone skips. A snippet that says "JWT refresh token handler" is less useful than one that says "JWT refresh token handler — handles the race condition when two requests refresh simultaneously, adapted from this auth library's approach." Six months from now you'll know what the snippet does. You won't know why you wrote it that way.
I have a template for code notes that forces three fields: what it does, when to use it, and what it doesn't handle. Takes 90 seconds to fill out. Has saved me hours of re-researching edge cases I'd already solved.
The Weekly Review Habit (The 20-Minute Version)
Every Friday, 20 minutes maximum. I've tried 60-minute reviews. They don't survive contact with real weeks.
The sequence: process inbox (move or delete), scan active project notes and add anything I want to remember from the week, check if any Obsidian notes should be promoted to structured Notion reference. That's it.
The Friday timing matters. Your context on the week's work is fresh. You haven't forgotten why you saved something. Do this on Monday and half the inbox is mystery content.
I use a recurring Obsidian note template for the review itself — a short checklist so I don't have to remember the process. Meta, but effective.
Connecting the Wiki to Real Work
The wiki only pays off if it reduces friction during actual work, not just during note-taking.
Three integrations I use constantly:
Project kickoff template — every new project gets a folder created from a template with sections for context, decisions log, useful links, and a notes dump. Takes 30 seconds, but future me always finds something useful in that decisions log.
Daily note as a scratchpad — I don't use the daily note for journaling or habit tracking. It's the first thing I open in the morning and it's where code fragments, error messages, and half-formed ideas land throughout the day. Most of it stays there and that's fine. The good stuff gets moved.
Search-first reflex — before Googling something technical, I search the vault. Takes three seconds. I'm surprised how often I find a note that already contains exactly what I need, or close enough. Building this reflex took about a month of deliberate practice.
Taking It Further
If you're building this from scratch or your current system is a mess you keep avoiding, the hardest part is usually the initial structure decision — not because it matters that much, but because the uncertainty makes you stall.
I put together a detailed guide called Dev Wiki Mastery: Your Second Brain Setup that covers the full system: the Obsidian configuration, the Notion templates I actually use, the snippet workflow, the review process, and how to migrate from a broken existing system without losing everything. It's practical documentation for developers who want to build this once and stop rebuilding it. You can find it at forge.closerhub.app/product/eb900cd9 for 12€.
The goal isn't a perfect knowledge base. It's a system that's slightly more useful than not having one, maintained with habits that are slightly less annoying than the problem it solves. That bar is achievable. Most elaborate PKM setups aim too high and collapse under their own weight.
Start with the inbox. Build the review habit before you build the structure. The rest can grow organically.