Skip to content

Brag Doc: Why and How?

Janahan Sivaraman
Janahan Sivaraman
4 min read
Brag Doc: Why and How?
You should be bragging about making onboarding docs.

I started keeping a Brag Doc at work in Aug 2018.

I learned about them from Julia Evans on Twitter. The premise is simple. You’re already doing awesome work, therefore, you should get recognized for it.

Since I started, I’ve been promoted every year - except for 1.

That year they shut down Engineering. We did impressive technical things. Couldn’t say the same about the business.

"Projects" section of Brag Doc from Aug 2018 - Dec 2018 at

Why do you need a Brag Doc?

Performance Reviews

It will save your butt come performance review season.

If your manager likes you, the Brag Doc will help them negotiate against other managers in calibration meetings. Calibration meetings are where managers are pitted against managers to fit employees to a curve of rewards; as defined by HR. Rewards are promotions and raises.

If your manager doesn’t like you, you’re fucked anyway.

Either way, your manager is always overloaded and busy. They will appreciate you preparing them for calibration meetings. You’re making their job easier.

Many companies include peer reviews into your performance reviews. When you ask someone for a review, provide them with your wins. Remind them of the awesomeness y’all accomplished together.

Incomplete Memory

Your manager has more reports than they should.

It’s unreasonable to expect them to remember every detail of your wins. Unless I kept a Brag Doc, I would forget many of the dope wins I had.

You already did the work, you should get recognized for it.

It’s easy to forget when you convinced a sibling team to prioritize your feature request. Or when you debugged a production issue for another team. Or when you designed and implemented a system that scaled beautifully - on a tight timeline.

This is even truer when everyday you’re heads down solving tough problems.

Documentation Section of Brag Doc (Aug 2018 - Dec 2018) when I worked at

Manager Transition

You'll be better prepared for unexpected manager changes.

Last year, my manager left in September 2021 and review season was in February 2022. That's nerve-wracking, especially in a year when real inflation is 17%.

Luckily, I kept a Brag Doc so my new manager could advocate for me come performance review season.

I was even able to secure a promotion from E6 to E7 in that same year.

Market Yourself

It’s not enough to add value.

You have to add value and make noise. At a bare minimum, keep your resume updated with these wins.

You can even write essays, tweets, or create video content around these wins.

These are skills you’ve picked up in industry. They are valuable. When we teach others and talk about them, it solidifies the concepts in our head.

That’s a superpower.

“People I’ve Helped” section from Brag Doc (Aug 2018 - Dec 2018) when I worked at

How do I keep a Brag Doc?

I start mine in a Moleskin notebook with college-ruled lines.

I update it on a daily basis with this shape.

I received a new laptop at work. I needed to set up the local development environment. I transferred these steps to a Github markdown document. This will be used for onboarding new Architects

About once every three months, I aggregate and filter the wins from the notebook into the Brag Doc:

I keep my Brag Doc as a Github Markdown doc

Points of note:

1. I separate the wins out by month. Visually, chunks of 3-4 items will make it easier to digest.

2. Between 2018 and 2022, I compressed the 5 columns into 1 column called “Wins”. I inline specs/docs as hyperlinks. I removed that section from the Brag Doc.

This is the shape of a “Win”: “My {{contribution}} in {{project-name}} enabled {{result}} with {{metric}}; accomplishing {{goal}}.

3. I added “competency” and “score” columns because that’s how my company evaluates software engineers. They give specific criteria associated with the score.

4. I upgraded “People I’ve helped” to “Endorsements”. As I am iterating through the wins, I filter what win helped which person. I follow up with them for an endorsement. These can also be leveraged in TC (total compensation) negotiations.

5. I highlight operational and engineering excellence wins. Making on-call better, contributing to runbooks, and pushing for RCAs are big wins for operational excellence.

Refactoring flaky dependencies can reduce pages. This improves quality of life for engineers and their families.

I keep a Brag Doc so I am ready to share my impact.

You should be ready, too.

You can grab the template here.

Next week, I will show you how to use this Brag Doc as part of the “TC Prep” strategy.  You can use this strategy to get a raise without threatening to quit.

I used the “TC Prep” strategy to increase my TC 41%.

Sign up for my newsletter so you don't miss it!


Janahan Sivaraman Twitter

Secrets to growing your career in Tech. Learning 2 languages "by ear". Recipes.

Related Posts

Members Public

Where To Start Learning Tamil

3 years ago, I couldn’t speak a full sentence in Tamil. Today, I can hold 45 minute conversations with native speakers. If I hadn’t found The Tamil Channel (Sabtha) on Youtube, my mother tongue would have died with me. A question I often get is “Janahan, where do

Where To Start Learning Tamil
Members Public

Detroit: Easiest Pizza To Make

Have you wanted to make pizza but worry it's too much work? For 15 years, I’ve been making pizza from scratch. For 13.5 years, those pizzas were mediocre. In the last 1.5 years, I purchased all five of the pizza guides from Notorious PIE. Those guides transformed

Detroit: Easiest Pizza To Make
Members Public

Kill Your Culture

Or live it. There is no in-between. I didn’t realize this until I left Maryland, where I grew up, in 2012. I missed my parent’s goat curry. The symphony of spices, aromatics, and tender meat that falls to pieces between my teeth. I couldn’t buy it. There

Kill Your Culture