A month later you don't remember why you did it that way.

Wrote a function. Works. A month later I look - why is this if here? Why exactly 100ms timeout? Where did magic number 42 come from?

Git blame shows who and when. Doesn't show why.

What I document

Not API. Not "this function takes X and returns Y". That's visible from code.

I document decisions:

• Why I chose this approach
• What alternatives I considered
• What constraints I accounted for

Format

File in work-log. Markdown. Date in filename.

# 2025-10-15: Why timeout 100ms

Problem: API requests sometimes hang.

Options:
- 50ms - too little, normal requests don't finish
- 500ms - too much, user waits
- 100ms - compromise, 95% of requests fit

Decision: 100ms timeout + retry 2 times.

How much time

5 minutes after decision. While I remember context.

ROI

Spent 5 minutes on document. Saved 2 hours on analysis a month later.

And AI helps better. Share document - it understands why it's done this way, doesn't suggest "improvements" I already rejected.