A brag document is a running list of what you have done at work, kept by you, in your own words, and updated while the details are still fresh. It is not a CV and not a status report: a CV is written for strangers and compresses everything, and a status report is written for this week. A brag document exists so that when someone asks what you accomplished over the last six or twelve months, the answer is retrieved rather than reconstructed.
Where the term comes from
The phrase was popularized by the programmer Julia Evans in a 2019 post, ‘Get your work recognized: write a brag document’, which argued a simple point: your manager cannot remember your work in the detail you can, and it is not reasonable to expect them to. The document is how you close that gap without relying on anyone's recall.
The idea predates the name—performance reviews have always rewarded people who kept receipts—but the naming mattered, because it made the practice something you could recommend to a colleague without it sounding like self-promotion.
What belongs in it
Most people list only shipped features and then wonder why the document feels thin. The categories below are the ones that get systematically dropped and are usually the strongest material in a review conversation.
- Work that shipped, with dates and one measurable outcome each.
- Work that was not a deliverable: code review, incident response, on-call weeks, interviews you ran, documentation nobody assigned.
- Mentoring and unblocking—who you helped, at what, and what changed for them afterwards.
- Decisions you influenced, including the ones where the argument was the contribution and the artefact was somebody else's.
- Things that failed, what you changed as a result, and what you would do differently. This section is what stops the document reading as marketing.
- Skills and context you picked up: a new system you now own, a domain you can now be asked about.
A worked example
The difference between a useful entry and a useless one is entirely specificity. Two versions of the same six months:
- Weak: ‘Improved the import pipeline. Helped onboard new team members. Contributed to the roadmap.’
- Strong: ‘Rewrote import retry handling (Jan–Feb). Silent failures went from roughly one a week to none in the two months since; failures now surface in the queue dashboard, so ops stopped finding them from customer reports. PR 2214.’
- Strong: ‘Onboarded two engineers in March and April—wrote the environment setup guide they both used, which cut first-commit time from about a week to two days.’
- Strong: ‘Argued against the multi-region rollout in the February design review; we deferred it and shipped the queue fix instead. The rollout was descoped in June for the same reasons.’
Why the timing of a review works against you
A review covers six or twelve months. The reviewer's clearest picture covers the last few weeks, because that is how attention works for everyone, including good managers. Work done in month two arrives at the conversation already faded, and work done by someone who left, on a project that was canceled, may not arrive at all.
There is a second, more mechanical problem: reviewers change. A manager who joined in April cannot assess January from memory, only from records—and the records that exist are tickets and calendar entries, which over-represent meetings and finished work and under-represent everything hard.
This is an observation about how reviews run rather than a research finding, and it is worth treating as such. But it is easy to check against your own last review, which is the only test that matters here.
How to fill it without another weekly ritual
A second document is difficult to sustain. The realistic version is to write little or nothing extra and assemble the brag document from material you already produce: dated entries about what changed that day, messages where you explained a decision, and notes taken after an incident.
That works if the raw material is retrievable by description rather than by location—asking ‘what did I do on the import pipeline’ and getting the entries that mention it, without having remembered in January that they would matter in December. With good source material, assembling half a year can take minutes rather than the hours required to reconstruct it from a calendar.
What a brag document will not do
It does not substitute for work being visible while it happens. A document produced at review time explaining six months of invisible contribution is a weaker position than having said it in March, and no amount of detail rescues it.
It is also culture-dependent. In some organizations, a written record reads as preparedness; in others it can look like lobbying. The version that travels best uses evidence rather than adjectives—numbers, dates, and names, with the judgment left to the reader. Numbers still need baselines: ‘reduced errors by 60%’ means little without the starting point, period, and method. Finally, no document changes a compensation band or a headcount freeze. A brag document helps when evidence is the missing part of the decision, and not when the constraint lies elsewhere.
Keep it running rather than writing it at review time, and make every entry specific enough to check: what changed, when, for whom, and by how much against what baseline. Include the unglamorous categories—review, on-call, mentoring, the argument you won in a design meeting—because those are the ones nobody else is recording.