Developer Journaling: A Tool for Retrospection and Growth
Three years ago, I wrote code every day but couldn't remember what I'd learned. I Googled the same errors two, three times. Six months later, I couldn't explain why I'd made a particular architectural decision.
Then I started keeping a developer journal. At first I thought "what's the point?" — but three months in, something changed. I could find solutions to problems I'd hit before in my own notes. During retrospectives, I could actually see what I'd accomplished that month.
Now journaling is as important a habit as writing code. Here's why it helps and how to do it well.
Why Developer Journals Actually Work
1. Memory Is Unreliable
Your brain rapidly discards things it judges "not important." That nginx config you wrestled with for three hours today? You'll remember half of it tomorrow and nothing by next week.
A journal is an external memory store. Instead of trusting your recall, you make records do the remembering.
2. Writing Forces Real Understanding
The fastest way to expose the illusion of understanding is to explain it to someone. Writing in a journal has the same effect. Mid-sentence you'll hit "wait... I don't actually know this part." That's exactly where real learning needs to happen.
3. You Start to See Patterns
Look back at three months of journals and you'll see: "I consistently get stuck on async error handling," or "technical debt accumulates in a predictable pattern." That's a map of your own growth.
4. It Becomes a Career Asset
"Tell me about a recent technical challenge you solved" stops being a hard interview question. At job search time, your journals are raw material for portfolio write-ups. Blog post ideas come straight from journal entries.
What to Write
TIL (Today I Learned)
Things you discovered today — big and small.
## TIL - 2026-03-21
- `Array.at(-1)` accesses the last element — no more `arr[arr.length - 1]`
- PostgreSQL `EXPLAIN ANALYZE` actually runs the query (unlike `EXPLAIN`), giving accurate cost figures
- React `useEffect` cleanup runs before the *next* effect too, not just on unmount
Looks minor, but accumulated over months it becomes an invaluable reference.
Blockers and Resolutions
Getting stuck and then solving it. These are the most valuable entries.
## Blocker - CORS Error (30 min)
**Symptom**
CORS error on local API calls. Server has `Access-Control-Allow-Origin: *` configured but errors persist.
**Tried**
1. Moved `cors()` middleware position → failed
2. Cleared browser cache → failed
3. Checked OPTIONS preflight request logs → found it here!
**Root Cause**
`cors()` middleware was registered *after* the auth middleware.
OPTIONS request hit auth middleware → received 401 → CORS headers never added → browser shows CORS error.
**Fix**
```javascript
// Wrong order
app.use(authMiddleware);
app.use(cors(corsOptions));
// Correct order
app.use(cors(corsOptions)); // CORS first
app.use(authMiddleware);
Lesson: Middleware order matters. OPTIONS requests must be handled before auth checks.
Skip this entry and six months later you spend another 30 minutes on the same problem.
### Architecture Decision Records
Why you chose a technology and what alternatives you considered.
```markdown
## ADR - State Management Library Selection
**Date**: 2026-03-21
**Status**: Decided
**Decision**: Zustand
**Context**
High-interaction dashboard. Need global state management.
**Options Considered**
| Option | Pros | Cons |
|--------|------|------|
| Redux Toolkit | Large ecosystem, standard | Heavy boilerplate |
| Zustand | Lightweight, simple setup | Lacks patterns for large apps |
| Jotai | Atomic updates | Team learning curve |
| Context API | No extra library | Re-render issues |
**Rationale**
Given team size (3 people) and app complexity, Zustand fits best.
If complexity grows, consider migrating to Redux.
**Review Date**: 2026-06-21
An ADR is a letter to your future self and teammates.
Energy and Focus State
Surprisingly useful for identifying your productivity patterns.
## Energy Log - 2026-03-21
- Morning: High focus. Worked through a complex algorithm problem start to finish.
- 2–4pm: Sharp energy dip. Code review or docs work probably better here.
- Evening: Light creative work clicked well (UI component work).
→ Block complex design work for mornings.
Journal Templates
Daily Template
# Dev Journal - YYYY-MM-DD
## Done Today
- [ ]
- [ ]
## TIL (Today I Learned)
-
## Blockers / Resolutions
> Blocker: [describe the problem]
> Resolution: [how you fixed it]
> Lesson: [what you took away]
## Tomorrow
- [ ]
## Energy / Notes
> Energy level: [1-10]
> Other:
Weekly Review Template
# Weekly Review - YYYY W[n]
## Completed This Week
-
## Learned This Week (TIL summary)
-
## Blockers and How They Were Solved
-
## What I Did Well
-
## What I'd Improve
-
## Goals for Next Week
-
## Level-Up Metrics
- New concepts learned: [n]
- Blockers resolved: [n]
- Blog post candidates: [list]
Monthly Review Template
# Monthly Review - YYYY-MM
## Major Work Completed
-
## Technical Growth
- New technologies/concepts learned:
- Topics I went deep on:
- Still-weak areas:
## Career
- Meaningful contributions:
- What I gave the team/org:
## By the Numbers
- Commit count:
- Issues resolved:
- Journal entries written:
## Next Month's Focus
1.
2.
3.
Choosing Your Tool
Obsidian
my-dev-journal/
├── daily/
│ ├── 2026-03-21.md
│ └── 2026-03-22.md
├── weekly/
│ └── 2026-W12.md
├── monthly/
│ └── 2026-03.md
├── til/
│ ├── javascript.md
│ └── postgresql.md
└── adr/
└── 001-state-management.md
Obsidian's strength is local markdown files + link graph. Writing [[CORS error fix]] auto-links related notes. The Daily Notes plugin creates today's file automatically.
Recommended plugins:
- Daily Notes: auto-create each day
- Templater: custom templates
- Dataview: query and aggregate journal data
- Calendar: weekly/monthly view
Notion
Better when you need team-level sharing. Database features make tag and date filtering easy.
Notion structure:
📁 Dev Journal
📋 Daily Log (Database)
- Date
- Energy (1-10)
- TIL count
- Blocker count
- Tags
📝 ADR (Database)
📚 TIL Reference (Database)
Plain Text + Git
The simplest and most durable approach. Markdown files in a Git repo.
# Structure
~/dev-journal/
2026/
03/
21.md
22.md
weekly/
W12.md
# Daily commit
cd ~/dev-journal
git add .
git commit -m "journal: 2026-03-21"
git push
Push to a private GitHub repo and you get search, version history, and access from anywhere. No tool lock-in.
Tool Selection Guide
| Situation | Recommended |
|---|
| Solo, local-first | Obsidian |
| Team sharing needed | Notion |
| Maximum simplicity | Plain text + Git |
| Need mobile access | Notion |
| Love graph/link exploration | Obsidian |
Tools are personal preference. The most important factor is which tool you'll actually use consistently.
Turning Journals into Blog Posts
The hidden value of journals: they're raw material for blog content.
Step 1: Flag Blocker Entries as Candidates
## Blog Candidates (from weekly review)
- [ ] CORS middleware ordering (2026-03-21)
- [ ] Redis cache eviction policy comparison (2026-03-19)
- [ ] Kubernetes readinessProbe vs livenessProbe (2026-03-15)
Step 2: Filter by Value
Good blog post test: "Would I have saved [X hours] if I'd known this?"
Step 3: Transform Journal → Draft
# Journal (raw)
CORS error. cors() middleware position issue. Was after auth middleware. Lost 30 min.
# Blog draft
## The Real Reason Your Express CORS Fix Isn't Working
If your CORS config looks right but errors persist, suspect middleware order.
### The Problem
...
### Root Cause
...
### Fix
...
### Lesson
...
A journal is a note to yourself. A blog post is an explanation for a reader. The transformation is rewriting through the reader's lens.
The Power of Retrospectives: Weekly and Monthly Reviews
Weekly Review Routine
30 minutes every Friday. Skim the week's entries:
- Compile TIL list (what did I learn?)
- Check for blocker patterns (same thing recurring?)
- Explicitly name one thing you did well
- Set next week's goals
# Weekly Review Checklist
- [ ] Read through all this week's entries
- [ ] Write TIL summary
- [ ] Note any recurring blocker patterns
- [ ] One specific win (be concrete)
- [ ] One actionable improvement for next week
- [ ] TOP 3 goals for next week
- [ ] Update blog post candidate list
Monthly Review: Growth by the Numbers
# Monthly Growth Dashboard - 2026-03
Technical Growth
- TIL entries: 42
- Blockers resolved: 18
- New libraries learned: 3 (Argo Rollouts, OpenTelemetry, Tempo)
Productivity
- Commits: 187
- PRs merged: 23
- Code reviews completed: 31
Community / Sharing
- Blog posts published: 2
- Internal knowledge share sessions: 1
Self-rating: 8/10
→ OTel integration shipped. Next month: focus on test coverage.
Numbers make "what did I actually do this month?" answerable.
Common Pitfalls
Perfectionism
A journal is a scratchpad. Typos and incomplete sentences are fine. 10 minutes of messy notes beats 2 hours of never-written perfect entries by 100x.
Trying to write too much
Start with one TIL line per day. Building the routine matters more than the content.
Quitting after missing a few days
You don't have to write every day. Write when you hit a blocker, learn something, or make an important decision. "Write when something happens" is more sustainable than "write every day no matter what."
Tool setup obsession
Many people spend three days configuring Notion and never write a single entry. Start with a text file today.
How to Start
One task for today:
# 2026-03-23
## TIL
-
## Something I Got Stuck On
-
## Tomorrow
-
Create this three-line file and fill in one thing per section from today. That's it. An imperfect journal started today beats a perfect system you'll set up later.
Six months from now, reading back through those entries and thinking "I remember wrestling with this — and I figured it out like that" — that's the win.