Manager READMEs: A minefield in the making

These documents are ostensibly meant to humanize, but ultimately backfire.

Duretti Hirpa

4 minute read

For as much as I want to take Twitter breaks, let’s be honest: I’m not. I’m going to fall sleep with my phone clutched in my right hand and wake up shining blue light into my precious orbs first thing. So, yes, I saw you manager-types. I saw you sharing your READMEs with delight - a cheeky throwback to how you used to operate as a developer. Get it? It’s technical documentation, but instead of for an API or open-source project it’s for me. Weird flex, but OK.

I thought I wouldn’t receive one of these documents. No one in my immediate sphere came off as this self-interested, I figured. I was wrong.

There it was. I returned from a two-week vacation, and buried under all the messages I was meant to read, one lay hidden, unassuming. A notification from Google drive. What’s this? I scan some more. XX README. “Are you serious?” I said aloud - forgetting my manager sits right next to me.

I scan the document - it’s totally non-offensive, but completely context-free. My eyes skip over the headings: meetings, feedback, biographical details. Why am I receiving this? I’ve been reporting to my manager for almost a quarter - this seems… ill-timed.


The one thing left out in the breathless admiration of manager READMEs is the reaction from your report. On Twitter, I saw managers delighting in the prospect of getting to skip the human interaction part. I find this reaction utterly bizarre – managers traffic in human interaction. It’s their one true currency. Why skip the step that will net you the most coins? Per usual Camille Fournier (manager to the stars and current managing director at Two Sigma), cuts right to it:

Look, fellow managers: there is no way to write these and not be self-serving. You are writing them presumably to shortcut problems that arise when people misunderstand your behavior or when they act in a way you don’t like or otherwise violate some expectations that you believe are within your rights to set.

She goes on to land this 1-2 punch:

If you want to build trust, you do that by showing up, talking to your team both individually and as a team, and behaving in an ethical, reliable manner. Over, and over, and over again. You don’t get it from writing a doc about how you deserve their trust.

Trust is consistency over time. We don’t get to skip ahead - especially not in a U.S. job-market as tight as it is. Sue Shellenbarger wrote about this phenomenon in the Wall Street Journal last month - discussing how perks aren’t attracting workers like they once did. No, what people crave is investment:

Coveted employees simply aren’t all that interested in working for companies that don’t give them the level of trust and motivation they want. “People expect to have a great manager now,” says Dr. Harter [chief workplace scientist at Gallup]. “They want to be able to see their future in the organization.”

READMEs aren’t a product of a great manager. Yes, setting a baseline is all well and good - but a great manager tailors their approach. Instead, shouldn’t a manager be requesting operating documents from her team? Figuring out how their reports work and adjust to see their report shine? Better yet, shouldn’t this exercise be a group activity? Operating manuals for all - democratize this urge.

Ultimately, a manager README isn’t a document about how we work. It’s about making a manager feel seen, behind a veneer of productivity. This is who I am! the README screams. This is how I operate! Don’t you understand, manager? This document is the performance of work. It’s a work like activity: it walks like work and talks like work, but it’s meaningless. More than this, we see you, manager. We know where you are because we lurk on your calendar. We know what you say because we analyze your every word. We see you, alright. We’ll be there, seeing, when your document fails to capture what you’re actually like - because no person fully knows themselves.

The old ways are fine. Stick to kindness. If you have to write this document, resist the urge to share it. You’re sending out a contract after all, and as your reports, you can bet we’ll hold you to it. If you can’t help yourself, then tailor your document to your individual reports - don’t blast it out, a one-size fits all. Your best bet is to build up trust through your actions. You can do it.