Why Most Brag Documents Don't Get Anyone Promoted (and What to Write Instead)
By Dominique Simmons ·
A brag document is a running record of your work and its results, kept through the year so the evidence is ready when promotion season comes. Engineer Julia Evans popularized the idea in a widely shared blog post, and it's good advice: writing things down as they happen beats trying to remember them later.
But most brag documents fail at the one job they're for. They're long, honest and detailed, and full of work done at the level you already have. A promotion committee reading one doesn't see someone ready for the next level. It sees someone doing their current job well.
Here's why that happens, what a promotable entry looks like instead, and how to check your own list before the cycle starts.
A long list isn't a strong case
Promotion decisions don't count accomplishments. They compare them against the criteria for the next level, and most of those criteria are about scope: how far your work reached beyond your own team.
Say the next level asks you to drive impact beyond your immediate team. You list four accomplishments against it. All four happened inside your team: a migration you led, a process you fixed, two launches you shipped. Each one was real work. Together, they're four examples of the level you're already at.
This is the failure you can't see in your own document, because every item on it really happened and really mattered. Length makes it worse. A longer list feels like a stronger case, so people keep adding entries at the same scope instead of looking for the one example that reached further.
The fix isn't a longer list. It's a list where every entry says how far the work reached.
You'll write it from memory, and memory edits
The second failure happens before you write a word. Most promotion cases are put together in the week or two before the deadline, from whatever you can still remember. Memory isn't a neutral record for this. It favors what happened recently and what was vivid, so the last two or three months crowd out everything before them.
It also keeps the wrong half. Memory researchers distinguish between gist, the general sense of what happened, and verbatim detail, the exact specifics. Gist lasts. Verbatim detail fades fast. (The idea comes from what psychologists call fuzzy-trace theory.) Months later, you'll remember that the migration went well. You won't remember that it finished three weeks early with zero downtime, or which director mentioned it at an all-hands. Those details are what make an entry persuasive, and they're the first to go.
Your manager has the same problem. When they write or present your case, they're working from their own memory of your year, with the same tilt toward the recent and the memorable. A document written as things happened corrects for both of you.
That's the real argument for a brag document. It isn't that you'll forget the work. It's that you'll forget the parts of it that count.
What a promotable entry looks like
A useful entry has five parts. Most brag documents have the first one and skip the rest.
- The outcome. What changed, not what you did. "Cut deploy time" is an outcome; "worked on CI" is an activity.
- The number. How much it changed, even roughly. A percentage, a count, a before and after.
- The scope. Who it reached: your team, your org, or the whole company.
- Who saw it. The people who can vouch for it, by name or role.
- The criterion. Which line on the next level's criteria it supports.
Brag document examples, before and after
| Role | Typical entry | Promotable entry |
|---|---|---|
| Engineer | Worked on CI improvements. | Cut CI pipeline time from 22 to 9 minutes; the two other backend teams adopted the same setup. Org scope. Seen by the platform lead. Supports "raises the technical bar." |
| Product manager | Led Q3 roadmap planning. | Ran Q3 planning jointly for three teams that had been planning separately; cross-team dependencies dropped from 14 to 5. Org scope. Presented to the VP of Product. Supports "influences decisions outside your reporting line." |
| Designer | Redesigned the settings page. | Redesigned account settings; related support tickets fell 35% the next quarter, and the pattern went into the design system. Org scope. Seen by the support lead and the design system team. Supports "drives impact beyond your immediate team." |
| UX researcher | Ran 12 customer interviews. | Ran 12 interviews that changed the pricing decision: leadership dropped the planned per-seat tier based on the findings. Company scope. Presented to the CEO and the pricing group. Supports "shapes product strategy." |
| Analyst | Built a churn dashboard. | Built the churn dashboard finance now uses for monthly forecasting, replacing a spreadsheet three teams maintained by hand. Org scope. Seen by the finance director. Supports "builds tools others depend on." |
| Engineer | Mentored junior engineers. | Mentored two engineers through their first on-call rotations; both now lead incident response without escalating. Team scope. Seen by the engineering manager. Supports "grows the people around you." |
The promotable versions aren't longer for the sake of it. Each one adds the number, the reach and the person who saw it, and that's what lets a committee judge the work without having been in the room.
Notice the last example stays at team scope, and that's fine. Not every entry needs to reach the whole org. Each one needs to reach the scope its criterion asks for. The problem is a document where every entry sits at team level while the criteria ask for more.
How to check your list for scope gaps
You can run this check in about twenty minutes, and it's worth doing at least a quarter before your promotion cycle, while there's still time to act on what it shows.
- Get the criteria in writing. Find your company's career ladder and copy the criteria for the level you want. If there isn't one, ask your manager what the next level looks like, and write down what they say.
- Tag every entry twice. Mark which criterion each entry supports, and whether its scope was your team, your org or the company.
- Look at the shape of your year. Count your entries by scope. Most people's lists are heavily weighted toward team-level work. That's normal. What matters is whether anything reaches further.
- Check each criterion. For every line on the ladder, ask two questions. Does anything on my list support it? And does at least one of those entries reach the scope it asks for?
A criterion with no entries is an obvious gap. The one to watch for is a criterion with several entries, none of them at the scope it requires. That's a scope gap, and it's the most common reason a case that looks full comes back.
What to do when you find one
You can't fix a scope gap by rewording the document. You fix it in the work. Take the gap to your manager and ask which next-level responsibility you could take on this quarter. Not more work. Different work.
Before that, check the entries you never tagged to any criterion. Work that didn't seem to fit anywhere is often where the best evidence is hiding, including the occasional org-wide project you forgot counted.
A ten-minute weekly habit
The format matters less than the timing. A brag document only beats memory if it's written close to when things happen.
- Every Friday, ten minutes. For anything that changed this week, write one entry with all five parts. Put the number in now, even a rough one. You won't find it later.
- If nothing changed, write nothing. An empty week is fine. A padded entry makes the real ones harder to find.
- Write down conversations too. When your manager says something about your promotion, or commits to something, note what was said and the date, the same day.
- Once a quarter, run the scope check. Twenty minutes, four steps, and you know what the next three months need to include.
Common questions
How long should a brag document be?
There's no right length. If you add an entry most weeks, a year comes to a few dozen. What matters is whether every criterion has evidence at the right scope, not how many lines there are. When you build the actual case, use the strongest two or three entries per criterion.
Should I share my brag document with my manager?
Yes, a curated version, ideally a quarter before the cycle. Give them your strongest entries, each matched to a criterion. It's the raw material for the case they'll present on your behalf, and they can only argue from what they have.
What if my work doesn't have numbers?
Use the closest measurable change: time saved, people affected, a decision that went differently, a problem that stopped happening. If none of those fit, a clear before and after works, and so does a named person who will vouch for the work.
When should I start a brag document?
Today, starting with the last three months. Write down what you can while those details are still fresh, then keep it weekly. Starting halfway through the year still beats starting the week of the deadline.
Where to start
If your promotion cycle is in the next six months, start with the check, then build the habit.
The free Promotion Case Readiness Check scores your case on five factors in about two minutes, including written feedback, manager alignment and sponsorship, the parts a brag document doesn't cover.
If you want the document and the scope check in one place, Career Growth Tracker is built for exactly this. You log each entry with its scope and the criterion it supports, and every criterion shows whether you've demonstrated it, are still building it, or have a scope gap.