Introduction
There is a quiet, persistent problem in the working life of most software engineers: the work disappears. Not the code - that lives in version control. Not the tickets - those live in Jira or Linear or whatever planning tool the team has settled on. What disappears is the shape of the work: the difficult conversation that unblocked a cross-team dependency, the refactoring decision that required four hours of reading old ADRs, the near-miss production incident that you caught at 11pm and quietly fixed before anyone noticed.
When performance review season arrives, engineers are asked to summarize their contributions over the past six months. Most of them open Jira, scroll through closed tickets, and try to reconstruct a narrative from artifacts that were never meant to tell one. The result is a flattened, incomplete account - measured in story points and deploys - that fails to represent what they actually did.
The solution is not complicated, but it is underused: keep a work log. Call it a brag document, a weekly journal, a ship log, or a captain's log if it suits you. The name does not matter. What matters is the practice of writing down, regularly and in your own words, what you worked on, what you decided, what you learned, and what got harder before it got easier.
This article is about why that practice is worth building, how to structure it, and how it quietly changes your relationship with your own work.
The Problem: Engineering Work Is Structurally Hard to Recall
Software engineers operate across multiple time horizons simultaneously. On any given day, a senior engineer might be debugging a subtle race condition, reviewing a colleague's pull request, attending a planning session for a feature that won't ship for six weeks, and responding to a Slack thread about an architectural decision made two quarters ago. The breadth is real, and the cognitive overhead is real.
Memory does not handle this well. Cognitive science research on memory - including foundational work by Hermann Ebbinghaus on the forgetting curve - shows that without active reinforcement, humans lose a significant portion of newly acquired information within days. Engineering work is no exception. The nuance of a trade-off discussion, the specific reason a particular approach was abandoned, the implicit context behind a comment left in a code review: these fade quickly.
The structural mismatch between how engineering work happens and how it is evaluated compounds the problem. Most organizations evaluate engineers on a cadence of six months to a year. Asking someone to recall the shape and impact of their work over that period without any intermediate documentation is like asking them to reconstruct a conversation from memory six months after it happened. What survives is impressionistic at best.
There is also a social dimension. Engineers who self-advocate clearly and confidently during reviews - who can say "In Q2, I did X and here is the measurable outcome" - tend to be perceived as more effective, regardless of whether the underlying work was actually stronger. This is not a comfortable truth, but it is a real one. A work log is not self-promotion; it is the raw material from which accurate self-representation becomes possible.
What a Work Log Actually Is
A work log, in the context used throughout this article, is a private running record maintained by an individual engineer - not a project management artifact, not a status report written for a manager, not a commit log. It is a document (or a collection of notes) that you write for yourself, with the expectation that you will re-read it in three to six months when you need to represent your work to others or make decisions about where to focus next.
The concept gained wider traction after Julia Evans published a piece titled "Get your work recognized: write a brag document" (2019), which named the practice and made explicit its connection to performance reviews. The framing resonated with a large number of engineers who recognized the gap between their actual contributions and what they were able to articulate when it mattered.
A work log is distinct from several things that might seem similar. It is not the same as a task list or a to-do tracker - those record work you intend to do, not work you have done and what you learned from it. It is not a personal wiki or second brain, though it can feed one. It is not a diary in the emotional sense, though it can include how you felt about a difficult situation. It occupies its own niche: retrospective, personal, honest, and oriented toward work specifically.
The format is flexible by design. Some engineers maintain theirs in a single Markdown file updated weekly. Others use daily notes in Obsidian or Notion, tagging entries by project or impact area. Others keep a physical notebook. The format that works is the one you actually maintain, and the bar for any given entry should be low enough that you write it even on days when you're tired. Friction is the enemy of consistency.
What to Record: A Practical Taxonomy
One of the reasons engineers don't keep work logs is that they're not sure what to write. The work feels too granular or too obvious to document. "I fixed a bug" does not feel like something worth capturing. But the useful question is not "was this impressive?" - it is "would I remember this in six months, and would it matter if I did?"
Accomplishments and Shipped Work
This is the most obvious category and the one Julia Evans' brag document framework emphasizes most. Anything shipped - features, fixes, scripts, internal tooling, infrastructure improvements - deserves an entry. The entry should go beyond the ticket description and capture something that a ticket cannot: the degree of difficulty, the unexpected obstacle, the thing you had to figure out that wasn't in any documentation.
A useful template for an accomplishment entry:
## 2024-03-14 - Shipped: async job queue refactor (PROJ-4421)
**What shipped:** Rewrote the background job processor to use a Redis-backed queue
instead of the previous polling model.
**Why it mattered:** The polling approach was causing ~15 unnecessary DB reads/sec
at idle. The new approach dropped idle DB load by ~90%.
**What was hard:** The migration path was non-trivial because we had ~400 in-flight
jobs during the cutover window. Wrote a dual-read approach to handle in-flight state.
**What I learned:** Redis LPUSH/BRPOP semantics are subtly different from what
I expected when dealing with consumer groups. Spent two hours on the wrong mental model.
Key Decisions and Their Context
Decisions are particularly worth capturing because they become invisible over time. Once a decision is made and implemented, the codebase reflects the outcome but not the reasoning. Six months later, when someone questions the choice or the context shifts, the reasoning is gone unless you recorded it.
This category overlaps with Architecture Decision Records (ADRs), but it is broader. An ADR is a formal artifact intended for team consumption. A work log entry about a decision can be rougher and more honest - including the options you considered and rejected, the constraints that aren't obvious from the outside, the person whose question changed your thinking.
## 2024-03-20 - Decision: keep validation in the service layer, not the database
We discussed moving constraint enforcement to DB-level CHECK constraints as part
of the schema review. I pushed back and we agreed to keep it in the service layer.
**Reasoning:** Our constraints are complex enough that expressing them in SQL would
require triggers or generated columns. The readability cost is high and testability
would suffer - DB-level logic is harder to unit test.
**Who was involved:** Discussion in arch-review with @marc and @priya.
**What could change this:** If we ever find ourselves bypassing the service layer
(e.g., bulk data migrations), we'd need to revisit.
Learnings, Reading, and Skill Development
Engineering work involves continuous learning that rarely shows up in any formal record. You read a paper about distributed systems consistency, or you spend an afternoon understanding how your database's query planner works, or you pair with a colleague and pick up a pattern you didn't know. None of this is visible to anyone but you.
These entries are worth keeping not just for performance reviews but for your own orientation. When you re-read your work log a month later, the learning entries give you a picture of how your understanding is evolving. They also create natural material for internal talks, blog posts, or mentoring conversations.
Key Discussions and Collaboration
Engineering impact frequently happens through conversations - a code review comment that prevented a design mistake, a Slack exchange that aligned two teams, a 1:1 where you helped a junior engineer work through a stuck point. These are systematically undercounted at review time because they leave no artifact.
Capturing them does not require long entries. A two-sentence note - who was involved, what shifted - is enough to jog your memory six months later and enough to count when you're building a case for your actual scope of impact.
Near-Misses, Incidents, and Things That Went Wrong
This is the most uncomfortable category and the most valuable. Writing about things that went wrong - mistakes you made, incidents you were part of, decisions that turned out to be wrong - is uncomfortable. But these entries are where the most durable learning happens, and they demonstrate something that polished accomplishment lists cannot: that you operate with rigor and self-awareness.
An entry about a near-miss should include what you noticed, what you did, and what you'd do differently. It does not need to be self-flagellating. The goal is accuracy, not performance of humility.
Implementation Patterns and Tooling
The Weekly Review Entry
The most sustainable cadence for most engineers is a weekly entry, written on Friday afternoon or Monday morning. The weekly cadence is frequent enough that you don't lose details, but infrequent enough that the overhead stays low. A good weekly entry takes fifteen to twenty minutes.
A template for a weekly entry:
## Week of 2024-03-11
### What I worked on
- PROJ-4421: async job queue refactor (shipped Thursday)
- Reviewed PR #892 for the new webhook retry logic (left comments on error handling)
- Planning session for Q2 auth rework
### What was hard or interesting
- The job queue migration was more involved than estimated. The dual-read approach
worked but I'd architect the data model differently next time.
- Marc's PR had a subtle bug where the retry logic doesn't account for idempotency
on POST requests. Left a comment. Good discussion.
### What I learned
- Read through the Redis BRPOP docs properly. Consumer groups are for a different
use case than I thought.
### What I'm thinking about
- The auth rework feels underspecified. The session invalidation story isn't clear.
Need to raise this before Q2 planning locks.
Obsidian-Based Daily Notes with a Periodic Rollup
Engineers who prefer finer-grained capture can use a daily notes approach - a short entry every day - combined with a weekly or monthly rollup. Obsidian's daily notes template feature makes this low-friction. The rollup is a separate file that aggregates the most significant items from the daily entries into a condensed summary suitable for review season.
<!-- Obsidian daily note template: daily-note-template.md -->
# {{date}}
## Done today
-
## Learned / noticed
-
## Blockers or open questions
-
## Who I helped or talked to
-
The daily template stays terse. The weekly rollup synthesizes. The pattern separates the cost of capture (low, daily) from the cost of synthesis (moderate, weekly), which makes both more sustainable.
Storing and Searching
The work log lives in a format you can search. Plain Markdown files in a Git repository, a Notion database, or Obsidian's vault all provide searchable plain text. Avoid formats that are difficult to search or export - a work log you cannot retrieve is not useful when you need it.
Tagging or categorizing entries by project, area of impact, or skill domain makes retrieval faster. A simple tagging convention like #shipped, #decision, #learning, #incident at the top of an entry is enough to filter meaningfully at review time.
How a Work Log Improves Prioritization
The most underappreciated benefit of a work log is not retrospective - it is prospective. A record of what you've done creates a feedback loop that changes how you make decisions about what to do next.
When you review your log regularly - not just at performance review time but monthly or quarterly - patterns become visible. You can see where your time is actually going versus where you think it is going. You can see whether the work you're doing is the work that matters to your goals. You can see whether you've been in a long stretch of reactive, maintenance-oriented work that is eroding your ability to build toward something larger.
This is particularly valuable for engineers targeting advancement. The gap between a strong individual contributor and a staff engineer is often not technical skill - it is scope of impact and the ability to operate proactively on the things that matter most. A work log makes the gap visible. If three months of entries show no strategic work, no cross-team influence, no decisions with lasting impact - that is not a comfortable thing to see, but it is useful information at a time when you can still do something about it.
The log also serves as a reference when scoping new work. When you're asked to estimate something, you can look back at similar past work - not just the ticket, but your candid assessment of what was hard and why - and produce a more grounded estimate. Engineering estimation is notoriously difficult; any process that grounds it in actual historical data is worth the overhead.
How It Affects Your Relationship With Your Own Work
This section is about something harder to quantify but real: the experience of ending a workday feeling like it mattered.
Software engineering is a profession with a visibility problem. Much of the best work is invisible to almost everyone outside the team - and often inside it too. A particularly elegant solution to a concurrency problem, a careful refactoring that reduced the cognitive load of a module others will maintain for years, a code review that improved someone's understanding of a pattern they'll use for the rest of their career: none of these announce themselves. They happen, they compound quietly, and then the day ends.
The pattern leads to a specific kind of fatigue: the sense that you worked hard but have nothing to show for it. Stand-up asked "what did you do yesterday?" and the honest answer is "I spent six hours tracking down why the test suite is flaky in CI and I think I know the answer but I haven't fixed it yet" - which sounds like nothing, even though it is not nothing.
Writing a work log entry about that six-hour investigation changes the relationship with it. The entry does not have to be polished. "Spent the day on the flaky CI problem. Root cause is a shared test fixture that's not being reset between suites. Filed PROJ-4489 with my findings. Haven't fixed it yet but I know what it is." That entry is honest, it captures real work, and it makes the day legible to future-you. The act of writing it has a closing effect - it names the thing and puts it somewhere, which allows you to actually leave the office (or close the laptop) without the unfinished feeling that the work was formless.
This is not productivity theater. It is closer to what cognitive behavioral therapy calls "cognitive closure" - the human need to have experiences feel complete rather than suspended. A work log is a lightweight mechanism for providing that closure at the end of a day, week, or sprint, without requiring the work itself to be finished.
Over months, the accumulated log also functions as a corrective to recency bias in self-evaluation. It is common for engineers to feel, in a difficult week, that they haven't made progress - that the quarter has been hard and unrewarding. Re-reading a month of entries tends to disrupt that feeling. The progress was real; it just wasn't salient.
Trade-offs and Common Pitfalls
Overhead vs. Depth
The most common failure mode for work logs is overcorrecting on depth and making the practice unsustainable. An engineer who sets out to write detailed entries every day will usually stop within two weeks. The bar for each entry should be low. A useful entry is one you actually write, not one that comprehensively documents everything.
Start with weekly entries. Make them rough. Resist the urge to polish. The log is not a publishable artifact; it is a working tool.
Completeness as a Trap
A related failure mode is attempting to capture everything and becoming paralyzed by what to leave out. The goal is not a complete record - it is a useful one. Useful means: recoverable six months later, honest about difficulty and impact, and covering the range of work rather than only the highlights.
If a week was genuinely uneventful and you write "quiet week - mostly reviewing PRs and attending planning meetings," that is a valid entry. It is accurate information about how your time was spent, and its absence from a log full of more substantial entries is itself meaningful data.
Keeping It Private vs. Sharing Upward
A work log written for yourself is different in tone from a document shared with your manager. The private version can include frustration, uncertainty, and self-criticism in ways that are useful for your own thinking but not appropriate for upward communication. Sharing your raw work log with a manager is generally not recommended.
What you can do is maintain a separate, curated "highlights" document - a distillation of your work log - that you share in monthly check-ins or 1:1s. This gives your manager visibility into your impact without exposing the roughness of the working document.
Not Reading It
A work log that is written but never re-read is only half as useful as it could be. Build a quarterly habit of reading back three months of entries - ideally the week before performance conversations, or the week you're deciding what to focus on next quarter. The re-reading is where the retrospective value appears.
Best Practices
Keep the bar low for daily and weekly entries. The capture phase should be nearly frictionless. You can always curate later. The goal at capture time is not quality - it is coverage.
Use a consistent template. Consistency reduces the cognitive cost of writing and makes entries comparable over time. Even a simple three-field template (what I did, what was hard, what I learned) is enough.
Date everything. Entries without dates lose their most important dimension. Dates allow you to reconstruct timelines, spot patterns, and connect work log entries to git history, PRs, or calendar events.
Capture decisions especially. Shipped work often has some trace in version control or project management tools. Decisions rarely do. A work log is one of the only places that the reasoning behind architectural and technical decisions gets recorded in a human-readable, searchable form.
Write about collaboration. The default content for a work log is individual output. But collaborative impact - mentoring, code reviews, alignment conversations - is often what distinguishes senior from mid-level engineers. Make a conscious effort to capture it.
Review and distill quarterly. Schedule a recurring time - a calendar block, not just an intention - to re-read the past quarter and distill the most impactful items into a summary. That summary becomes your performance review raw material, your answer to "what have you been working on," and your input for planning the next quarter.
Don't wait for the perfect format. The format you'll actually use is better than the format you've been designing. Start with a text file and today's date. Iterate from there.
Conclusion
A work log is, in its simplest form, a decision to take your own work seriously enough to write it down. The technical sophistication required is zero. The consistency required is modest - fifteen minutes a week, at a sustainable cadence. The return, over six months or a year, is substantial: a clear record of what you built and decided, a corrective to the natural human tendency to underestimate progress, and raw material for the performance conversations that have real consequences for your career.
The deeper point is not about performance reviews at all. It is about engineering as a craft practiced over time. The engineers who get better faster are usually the ones who reflect on their work deliberately - who notice when an approach failed, who capture the context that made a decision non-obvious, who can say with some precision what they learned in the last quarter. A work log is a low-overhead mechanism for making that reflection habitual.
Start the log today. Not with a perfect template or a carefully chosen tool - just a file, a date, and three sentences about what you did this week. The practice will compound in ways that are hard to see at the beginning and impossible to ignore at the end.
Key Takeaways
-
Start with a weekly entry, not a daily one. Frequency kills consistency. Weekly is sustainable; daily is aspirational. A consistent weekly log beats an intermittent daily one every time.
-
Capture decisions, not just output. Shipped work has traces in other systems. Decisions do not. The reasoning behind a technical decision is almost always lost unless you write it down the week you made it.
-
Record collaboration explicitly. Mentoring, code reviews, alignment conversations, and cross-team unblocking are systematically undercounted in reviews because they leave no artifact. Name them in your log.
-
Re-read quarterly, not just at review time. The retrospective value of a work log compounds with regular reading. Build a recurring calendar block to review and distill the past quarter - not just the week before a performance conversation.
-
Use the log to audit your time allocation. If three months of entries show mostly reactive, maintenance-oriented work with no strategic contribution, that is actionable information. A work log is a prioritization tool, not just a record.
Analogies and Mental Models
The Ship's Log. Naval vessels have maintained detailed logs of their position, cargo, crew, and events since antiquity - not because any individual day was interesting, but because the accumulation of daily entries made it possible to reconstruct what happened, defend decisions to authorities, and learn from past voyages. A work log operates on exactly the same principle.
The Fitness Log. Athletes who track their workouts improve faster than those who don't - not because logging is the training, but because it makes progress visible, surfaces what's working, and prevents the common mistake of repeating the same plateau week after week. A work log does the same for engineering skill development.
The GPS vs. Dead Reckoning Problem. Without a log, engineers navigating their own careers are using dead reckoning - estimating where they are based on general sense of direction and elapsed time. A work log is the GPS: it gives you a ground truth reading on where you actually are, independent of where you feel like you are.
The 80/20 Insight
Most of the value in a work log comes from doing two things well: capturing decisions and their context in the week they're made, and reading back quarterly rather than only at review time. Everything else - format, tagging, tooling, entry frequency - is optimization. If you do only those two things, you will recover eighty percent of the benefit with twenty percent of the possible overhead.
The decisions matter most because they are the least recoverable from any other source. The quarterly reading matters most because it is the mechanism that converts a passive record into an active tool for self-direction. Get those two habits right before optimizing anything else.
References
- Evans, Julia. "Get your work recognized: write a brag document." jvns.ca, August 2019. https://jvns.ca/blog/brag-documents/
- Ebbinghaus, Hermann. Über das Gedächtnis: Untersuchungen zur experimentellen Psychologie (Memory: A Contribution to Experimental Psychology). 1885. Translated and published by Columbia University, 1913.
- Nygard, Michael T. Release It!: Design and Deploy Production-Ready Software (2nd ed.). Pragmatic Bookshelf, 2018. (On incident documentation and post-mortems as learning artifacts.)
- Winters, Titus; Manshreck, Tom; Wright, Hyrum. Software Engineering at Google: Lessons Learned from Programming Over Time. O'Reilly Media, 2020. (On engineering culture, documentation practices, and long-term code health.)
- Fowler, Martin. "Architecture Decision Records." martinfowler.com, 2020. https://martinfowler.com/bliki/ArchitectureDecisionRecord.html
- Loehr, Jim; Schwartz, Tony. The Power of Full Engagement: Managing Energy, Not Time, Is the Key to High Performance and Personal Renewal. Free Press, 2003. (On cognitive recovery, closure, and sustainable high performance.)
- Allspaw, John. "On Being a Senior Engineer." Kitchen Soap, 2012. https://www.kitchensoap.com/2012/10/25/on-being-a-senior-engineer/ (On the self-assessment habits of effective senior engineers.)