You've debugged the same cryptic PostgreSQL deadlock issue twice. You've googled the same regex syntax four times this month. You've explained your team's deploy process from memory to the third new hire in a row. Somewhere in your browser history, your Notion, your Slack DMs to yourself, and three different GitHub gists lives every answer — you just can't find it when it counts.
This is the knowledge management problem nobody talks about in developer circles. Not because it doesn't matter, but because most of the advice out there is built for writers and project managers, not engineers who context-switch between debugging sessions, architecture decisions, and code reviews before lunch.
Here's the system I've built that actually works.
The Core Problem: Capture Friction Kills Habits
Every PKM system fails the same way. You set up a beautiful Notion workspace with nested databases and emoji-coded pages. You use it for two weeks. Then you hit a crunch period, skip capturing for three days, and the habit collapses. By month two, it's a ghost town.
The fix isn't better tooling — it's lower friction at the capture layer.
Your capture method needs to require zero context-switching. For code-related notes, I use a single floating scratchpad (Win+Space on Windows, ⌘+Space on Mac) that dumps raw text into a daily inbox file. Not organized. Not formatted. Just dumped. The format is: timestamp, source, raw content. That's it.
2026-05-07 14:32 | PostgreSQL fix
ALTER TABLE orders ADD COLUMN IF NOT EXISTS processed_at TIMESTAMPTZ;
-- "IF NOT EXISTS" not available before PG9.6, use DO block instead
Daily inbox, zero friction, no decisions. You organize later — you capture now.
Your Three-Layer Architecture
Most developers try to maintain one flat structure. That's why search becomes useless after six months. The system that scales looks like three distinct layers:
Layer 1 — Inbox: Raw captures from today. Processed weekly. Lives in one file per day.
Layer 2 — Reference Library: Processed, evergreen notes. Organized by domain (infra, frontend, databases, APIs, etc.), not by project. A note on "Redis TTL behavior" belongs in databases, not in the "Project X" folder — because you'll need it again on Project Y.
Layer 3 — Projects: Time-bound, contextual. Decisions made, architecture chosen, open questions. Archived when the project ships.
The critical habit: every Friday, spend 20 minutes processing your inbox. Move anything worth keeping to Layer 2. Delete the rest. This weekly processing session is the only "maintenance" your system needs.
What Actually Goes In Your Wiki
The biggest mistake developers make is trying to document everything. Wrong instinct. You should only capture things where the retrieval cost is high:
Yes — capture these:
- Error messages with non-obvious solutions (especially if Stack Overflow was useless)
- Configuration patterns you'll reuse (
nginxproxy headers,docker-composenetworking quirks) - Decision records: why you chose library X over Y, with the tradeoffs explicit
- API gotchas that aren't in the docs (rate limit behavior, undocumented fields, auth edge cases)
- Team-specific tribal knowledge (deploy checklist, staging environment quirks)
No — skip these:
- Things easily searchable in official docs
- Project-specific business logic (that belongs in the repo's ADR)
- Meeting notes that don't contain a decision or action item
A good test: "Would a future me, on a different project, need this?" If yes, it belongs in the Reference Library.
Retrieval is the Real Product
Your wiki is useless if you can't find things. Most developers over-index on organization and under-index on retrieval. The truth: links beat folders.
Instead of deciding where a note "lives," link it from multiple contexts. Your note on "Redis TTL gotchas" should be linked from your "Caching Patterns" note, your "Performance Debugging" note, and any project note where Redis was involved. Bidirectional links (Obsidian does this natively) mean you discover related notes without remembering where you filed them.
For quick retrieval, maintain a small "Map of Content" (MOC) per domain — a single note that's just an index of your most-used references in that area:
## Databases MOC
- [[PostgreSQL deadlock debugging]]
- [[Redis TTL and eviction behavior]]
- [[MySQL vs Postgres: when to choose which]]
- [[Connection pooling patterns]]
This becomes your jumping-off point when you enter a domain. No more search-and-hope.
Tool Recommendations (Without the Holy Wars)
The tool debate is a distraction. But here's a practical answer:
Obsidian if you want local-first, offline, Git-syncable, and you're comfortable with markdown. The graph view is genuinely useful for discovering connections. Use it with the Dataview plugin for dynamic queries across your notes.
Notion if you're already embedded in it for project management and want one tool. Use its database views to build a proper reference library with metadata (tags, domains, date added). Don't use it as a daily driver for capture — the editor is too slow for quick notes.
The hybrid that works best: Obsidian for your personal Reference Library and daily notes, Notion for collaborative team wikis. Two tools, two clear purposes, no overlap confusion.
Regardless of tool: enable a global hotkey that opens a new note instantly. Remove the friction between "I need to remember this" and "note created."
Making It Stick: The Only Habit That Matters
Systems don't fail because of bad tooling. They fail because there's no trigger for capture. Build capture into existing moments:
- When you close a debugging session: 90-second note on what the fix was
- When a PR gets merged: add any non-obvious decisions to your wiki
- When you answer the same Slack question twice: that's a wiki entry waiting to happen
The compounding effect is real. After six months, you'll have a reference library that makes you noticeably faster. Not because you're smarter — because you've stopped paying the re-learning tax on everything you've already solved.
The developer who writes things down doesn't just remember more. They think more clearly, because the act of writing forces you to understand what you actually learned, not just that you fixed it.
I compiled everything into a practical guide: Dev Wiki Mastery: Your Second Brain Setup
Top comments (0)