A brag document is a running, self-maintained log of what you shipped, what it changed, and who you helped, written down while you still remember the details. It is the one artifact that makes promotion packets, performance review self-assessments, and resume updates fast instead of agonizing, because all three are different edits of the same source file. The habit costs about ten minutes a week. The alternative is reconstructing a year of work from Slack scrollback and commit history the night before your self-review is due.
The term spread through Julia Evans' 2019 post Get your work recognized: write a brag document, and her framing is worth taking literally rather than flattening into generic "track your wins" advice. Her central observation is that if you do not remember everything important you did, your manager probably does not either. Almost every practical rule about brag documents falls out of that one sentence.
This article is about the document itself. The process it feeds, rubrics, promo committees, calibration, is covered separately in how to get promoted to senior engineer.
Why does a document beat just doing good work?
Because the systems meant to notice your work are weaker than most engineers assume, and they run on a much shorter memory than a year.
Gallup's research on performance management found that 56% of employees formally review their performance goals with their manager once a year or less. That is the entire feedback loop for many people: one conversation, reconstructed from whatever both parties happen to recall. Your manager is holding six to ten of those reconstructions in their head at once, weighted heavily toward the last two months, and they were not in the room for most of your work.
Harvard Business Review's guide to making performance reviews fairer points at the structural half of the problem: when evaluation criteria are vague and open-ended, it becomes easy for patterns of bias to slip into the process. You cannot rewrite your company's rubric. You can remove the part you control, which is showing up to a high-stakes conversation with a blank page and a vague sense that the year went well.
Industry insight
"A mere 22% of employees strongly agree that their performance review process is fair and transparent."
— Gallup, 2% of CHROs Think Their Performance Management System Works
A brag document does not make an unfair process fair. It makes you the best-informed person in the room about your own year, which is a meaningfully different position from being the person trying to remember what happened in March.
What actually goes in a brag document?
Five categories carry almost all the weight. Everything else is optional.
Shipped work with the impact attached. Not "migrated the billing service to the new queue." Instead: what was broken or slow before, what you did, and what changed afterward. One line of before, one line of after. If you only log the first half, you have written a task list, which is the most common way this habit fails.
Collaboration and mentoring. Code reviews that actually taught someone something, onboarding the new hire, the design doc that unblocked another team, the internal talk, the runbook people still use. Evans lists collaboration and mentorship as its own section for a reason: it is the category most reliably invisible to anyone reading a commit history, and it is usually a large part of what separates a senior engineer from a productive mid-level one.
Things you fixed that nobody asked you to fix. Evans calls this the "fuzzy work," and names examples like improving code quality on the team and driving down technical debt. Flaky test suites, a deploy that needed three manual steps, an alert that paged everyone at 3am for nothing. This work has no ticket, no launch announcement, and nobody to vouch for it unless you do.
Numbers, wherever they genuinely exist. p99 latency before and after. Build time cut from 14 minutes to 5. Incident count in your service for the quarter. Share of users on the feature you shipped. Do not invent numbers to look better, and do not invent them to fill a template. Evans' advice is to make your work sound exactly as good as it is, and a fabricated metric is the fastest way to lose the credibility the whole document exists to build.
Scope growth and what you learned. New systems you now own alone, decisions you make without sign-off, the on-call rotation you joined, the technology you picked up well enough to review other people's work in. Scope creep is invisible to most managers until somebody writes it down, which is also the core of the case in how to ask for a raise without another offer.
Two things to leave out: anything you would not say out loud in a review, and polish. This is a working file, not a publication.
What cadence actually survives?
A ten-minute weekly append beats a heroic quarterly rewrite, and it beats it for a reason that has nothing to do with discipline. The weekly version is a recall task. The quarterly version is a reconstruction task. By week nine you are no longer forgetting details, you are forgetting that the work happened at all.
Evans notes that many people have told her a few minutes every two weeks works best for them, while she personally prefers a single long session every six months. Both work. What does not work is intending to do the long session and then not having the inputs when the deadline arrives.
What makes the weekly version stick in practice:
- Attach it to something that already happens. End of Friday, after standup notes, right before you close your laptop. A recurring calendar block with the document linked in the invite removes the "where did I put that file" friction that kills this habit in week three.
- Append, never edit. New entries go at the top with a date. Do not reorganize, do not rewrite old entries, do not build a taxonomy. Reorganizing is a separate job you do twice a year, when you actually need output.
- Write badly on purpose. "Fixed the retry storm thing, Carlos said it was causing the Tuesday pages, check the postmortem" is a perfectly good entry. The polished version can be written later from this. It cannot be written from nothing.
- Use your own tooling as input, not as the document. Your merged pull requests, closed tickets, and shipped design docs are the raw feed. Skimming them takes two minutes and triggers the memories that matter. The document is where you record why any of it counted.
- Log positive feedback verbatim. Paste the Slack message, the review comment, the thank-you from another team, with the name and date. Paraphrased praise is weak evidence. A quoted sentence with an author attached is strong, and it is the single highest-value thing you will copy into a self-assessment.
Keep it somewhere you control and can take with you: a plain Markdown file in a personal repo, a private note, a doc in your personal account rather than your work one. Details about internal systems should stay internal, but the record of your own career should not disappear when your account is deactivated.
How does one document turn into three different artifacts?
The document is a single source. The three things you build from it have different audiences, different time windows, and different framings, and conflating them is why many engineers' promo packets read like status reports.
| Artifact | Audience | Time window | Framing |
|---|---|---|---|
| Promo packet | People who may never have worked with you | 12 to 24 months | Evidence you already operate at the next level, consistently |
| Review self-assessment | Your manager, who knows the context | The review period only | Outcomes mapped to the goals set when the period opened |
| Resume bullets | Recruiters and hiring managers outside the company | Whole role | Portable outcomes with zero internal jargon |
The promo packet needs a sustained pattern, not highlights. One excellent quarter is a good quarter. Four quarters of independently owning ambiguous problems is a level change. Pull the entries that show the same behavior repeating, and lead with scope and autonomy rather than volume. Your document's job here is mostly to prove duration.
The self-assessment is period-bounded and should be organized against whatever goals were set when the period opened, even if your best work that period was unplanned. Managers write their version of your year from somewhere, and a specific, dated, quoted self-assessment is usually the most detailed input available to them. This is where the verbatim praise you logged earns its keep.
Resume bullets need the heaviest translation. "Reduced p99 checkout latency from 1.8s to 400ms by replacing synchronous inventory calls with a cached read path" survives contact with someone who has never heard of your internal service names. "Led the Mercury migration" does not. Strip the internal nouns, keep the numbers, lead with the outcome. The level of detail your document holds is exactly what makes a role-specific rewrite possible later, which is the hard part of a senior software engineer resume.
The failure mode: logging activity instead of outcome
This is the one that quietly ruins the habit, and it looks like success while it is happening. The file fills up, you feel organized, and at review time you discover you have written a longer version of your ticket queue.
The test is a single question after each entry: so what? If the answer is "it got done," the entry is incomplete.
| Activity log | Outcome log |
|---|---|
| Migrated 14 endpoints to the new auth service | Finished the auth migration, removing the last dependency that blocked the SSO launch |
| Wrote the Kafka consumer design doc | Design doc settled a two-month debate between two teams, and the chosen approach shipped in Q3 |
| Reviewed 120 pull requests | Reviewed most of the team's pull requests this quarter, including onboarding two new hires to the service |
| Fixed flaky tests | Cut CI failure rate from roughly one in three runs to under 5%, which ended the habit of re-running builds blindly |
The right-hand column is not longer because it is padded. It is longer because it contains the part a stranger needs in order to care. When you cannot find the outcome for a piece of work, that is useful signal too: either the impact exists and you have not asked who benefited, or you spent real time on something that did not matter, which is worth knowing well before somebody else points it out.
One more common miss: recording only the things that worked. A project you killed early because the data said it would not pay off, or an incident you ran that produced three process changes, are both strong entries. Judgment is a senior behavior, and it rarely leaves a green checkmark behind.
How to start one this week
Open a blank file. Write today's date. Spend fifteen minutes going through the last month of your merged pull requests and closed tickets, and write down the five things you would be annoyed to see left out of your review, each with a before and an after. Then put a fifteen-minute block on your calendar for Friday with the file linked, and append to it. That is the entire setup.
The first retroactive pass will feel thin, because you are already working from a degraded memory. Six months of weekly appends later the problem inverts: you will have more real evidence than the self-assessment form has room for, and your job becomes selection rather than recall. That is the position worth being in.
Key takeaways
Your manager will not remember your year, so record it yourself
Gallup found that 56% of employees formally review their goals with a manager once a year or less. That single conversation runs on two imperfect memories, and only one of them is yours to improve. Writing things down is the cheapest intervention available to you.
A ten-minute weekly append beats a heroic quarterly rewrite
Weekly logging is recall. Quarterly logging is reconstruction from a memory that has already decayed. Attach the habit to something that already happens on your calendar, append with a date, and let the entries be rough.
Record outcomes and before-and-after state, not completed tasks
Ask "so what" after every entry. If the answer is "it got done," the entry is incomplete and will be useless in nine months. The outcome is the part a promo committee or a recruiter actually needs to read.
One document feeds three artifacts with three different framings
A promo packet needs a sustained pattern over twelve to twenty-four months, a self-assessment needs outcomes mapped to that period's goals, and resume bullets need portable numbers with internal jargon stripped out. Same source, three different edits.
Log collaboration, unasked-for fixes, and praise with names attached
Mentoring, design docs, flaky-test cleanup, and the alert you quietly fixed leave almost no trace in a commit history. Quoted feedback with an author and a date is far stronger evidence than your own paraphrase of it later.
Frequently asked questions
How long should each brag document entry be?
Two to four sentences is plenty: what the situation was, what you did, what changed, and who can confirm it. Anything shorter usually loses the outcome, which is the part you will need later. Anything longer tends to become a writing project you start skipping. Link to the pull request, doc, or postmortem instead of summarizing it inside the entry.
What if my work genuinely has no numbers attached to it?
Plenty of valuable engineering work is unmeasured, and inventing a metric is worse than having none. Use before-and-after state instead: what was impossible or painful before, what became possible after, and who said so. A named colleague confirming that your design doc unblocked their team is concrete evidence even with no percentage in it.
Should I share my brag document with my manager?
Share a cleaned-up subset, not the raw file. Evans suggests sharing it with your manager and your peer reviewers, and in practice a short summary sent ahead of a one-on-one or a review cycle is what lands. Keep the messy append-only version private so you never hesitate to log something half-formed or unflattering.
Is a brag document the same thing as a promotion packet?
No. The brag document is the raw, continuous input. The packet is one dated, audience-specific output built from it. The packet argues a single claim, that you already operate at the next level, and cites only the evidence supporting it. The document holds everything, including work that will never make a packet but may belong on a resume.
How far back should I go when starting one from scratch?
One month of real detail is more useful than two years of vague recollection. Do a quick pass over the last quarter to capture anything you would be upset to lose, then switch to forward-only weekly appends. Trying to reconstruct your entire tenure before you begin is the most reliable way to never begin at all.
Keep the document, run the weekly append, and reuse it for every review and every resume update. And when you do decide to find out what your documented scope is worth on the open market, the record you already built is most of the work: browse what is open on hire.monster/jobs and start from evidence rather than memory.