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:

1. Compile TIL list (what did I learn?)
2. Check for blocker patterns (same thing recurring?)
3. Explicitly name one thing you did well
4. 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.