DEV Community

AppZ
AppZ

Posted on

How I Built a Developer Knowledge Base in Obsidian That I Actually Use

#obsidian #productivity #devtools #programming

Every developer I know has the same problem: knowledge scattered across five places at once.

Browser bookmarks they never re-read. Notion docs that become graveyards. Slack threads with critical context that disappear into the archive. README files that contradict each other. Stack Overflow answers bookmarked with zero recall of why.

I tried most of the "second brain" setups and none of them stuck until I figured out why they kept failing: generic productivity systems are not built for how developers actually think and work.

A developer's knowledge is fundamentally different from a writer's or a manager's. It is:

  • Code-linked (a note about a library is useless without the actual code it explains)
  • Decision-heavy (architecture decisions need context, rationale, and alternatives considered)
  • Debugging-intensive (solutions to bugs need the exact error message, environment, and what you tried)
  • Time-sensitive (that API migration note is only relevant for a 3-month window)

Here is the structure that actually worked.

The Core Structure 

00-Inbox/
10-Projects/
20-Areas/
  - Language: Python/
  - Stack: AWS/
  - Domain: Auth/
30-Resources/
  - Libraries/
  - Tools/
  - Patterns/
40-Archive/
Enter fullscreen mode Exit fullscreen mode

The key insight: Resources are evergreen, Projects are temporary, Areas are ongoing responsibilities.

A note about how JWT works lives in 30-Resources/Domain-Auth/. A note about implementing JWT for the current sprint lives in 10-Projects/Sprint-42-Auth-Revamp/. When the sprint is done, the project gets archived. The JWT fundamentals note stays forever.

The Templates That Made It Click

Architecture Decision Record (ADR) 

# ADR-042: Use Postgres over DynamoDB for user sessions

Status: Accepted | Date: 2026-06-22

## Context
We need session storage that supports complex queries for the audit log feature.

## Decision
Postgres with connection pooling via PgBouncer.

## Alternatives Considered
- DynamoDB: rejected (query limitations for audit log requirements)
- Redis: rejected (not durable enough for compliance requirements)

## Consequences
- Positive: Full SQL query support for audit reporting
- Negative: Need to manage connection pool tuning
Enter fullscreen mode Exit fullscreen mode

This template changed how our team makes decisions. When someone asks "why did we choose X six months ago?" the answer is one Cmd+O search away.

Debug Log 

# Debug: [error message or symptom]

Date: 
Environment: 
Reproduction Steps:

## What I Tried
- Attempt 1: [result]
- Attempt 2: [result]

## Root Cause

## Fix

## Links
Enter fullscreen mode Exit fullscreen mode

The discipline here: write the debug log BEFORE you fix it, not after. The moment you close the bug you lose 80% of the context. The notes you write mid-investigation are the ones that actually help future-you.

Code Snippet Vault 

# [What this does in plain English]

Tags: #python #pandas #data-cleaning

## Use When
[Specific scenario this applies to]

## Code
Enter fullscreen mode Exit fullscreen mode


python

the actual code 


## Gotchas
- [Edge case 1]
- [Edge case 2]

## Source
[Link to SO answer, docs page, or colleague who showed you this]
Enter fullscreen mode Exit fullscreen mode


datastudio

The "Use When" field is what separates useful snippets from ones you never re-find. If you cannot write one sentence about when to use it, you probably do not understand it well enough to save it.

The Dataview Queries That Make It Useful

Install the Dataview plugin and add these to your homepage:

Open architecture decisions (needing review):

TABLE status, date FROM "20-Areas"
WHERE contains(file.name, "ADR") AND status != "Accepted" AND status != "Superseded"
SORT date DESC
Enter fullscreen mode Exit fullscreen mode

Notes tagged with a specific tech stack:

LIST FROM #aws AND #lambda
SORT file.mtime DESC
LIMIT 10
Enter fullscreen mode Exit fullscreen mode

Recent debug logs (last 14 days):

TABLE file.mtime as "Date" FROM "10-Projects"
WHERE contains(file.name, "Debug")
WHERE date(file.mtime) > date(today) - dur(14 days)
SORT file.mtime DESC
Enter fullscreen mode Exit fullscreen mode

What Actually Changed My Behaviour

The three things that made this stick where other systems did not:

1. The quick capture shortcut. I have a hotkey that opens a new note in 00-Inbox/ in under a second. If capturing requires more than one action, you stop capturing during flow state.

2. Weekly 20-minute inbox processing. Every Monday, everything in 00-Inbox/ gets filed, linked, or deleted. The inbox is not storage -- it is a queue.

3. The "what would make this note findable" principle. Before closing any note, I ask: if I search for this in 6 months with a vague memory of what it's about, what search term will I use? Then I make sure that term is in the title or first paragraph.

Getting Started Without Building From Scratch

The hardest part is the initial structure and templates. You can build everything above yourself in a few hours, or use a pre-built Developer KB OS with the ADR, debug log, snippet vault, and Dataview queries already wired up.

I put one together and it's available at zarchitectstudio.gumroad.com/l/rncjp -- but everything in this post is enough to build your own if you prefer starting from scratch.

The setup matters less than the habit. Pick a structure, commit to it for 30 days, and adjust from there.

Top comments (0)