This article is long overdue. I promised I’d get around to writing it over two years ago, when welcoming Brandon Hays to my team. I asked him his thoughts on Manager READMEs, to which he responded: “I absolutely hate them.”

“Got it,” I replied. “I wrote one and shared it with you, and I’d like you to consider writing one too.”

A spirited discussion about the topic ensued. When we were ready to move on to other topics, I expressed my appreciation for his candor, asked him to read what I’d written and watch a short internal talk I gave on the topic, and told him I looked forward to having future discussions on this and other topics. This stuff is hard, and nobody has all the answers.

He remarked a few months later in his podcast that he’d changed his opinion on them. He asked me if I’d consider rebranding the concept, noting that the doc I’d written didn’t exhibit the issues called out in an article we’d read, and I told him I’d rather reclaim the existing term. This article is my attempt to do just that.

What’s a Manager README?

Let’s get the dictionary definition out of the way: A Manager README is documentation about a person, not unlike a README you might include in a software project’s git repository.

Note what this definition most explicitly does not include: “user guide” or “operator’s manual”. I sincerely believe that early proponents of Manager READMEs did them a massive disservice by the metaphors they chose to describe them, and those were two common ones. They start you in a mindset of writing product documentation, and not project documentation.

Starting from there, it’s not difficult to see how things can go horribly wrong. After all, we ship user guides with products we deem production-ready, but documentation written for collaborators on a work in progress looks different. And I promise you: if you’re human, you’re a work in progress, and everyone you meet is a potential collaborator. That changes things.

So, while we’re talking about what Manager READMEs aren’t, let’s get a few other things out of the way. In addition to not being a user guide or operator’s manual, Manager READMEs are not…

• primarily for you
• a replacement for the daily work of trust-building
• a place to vulnerability floodlight
• a laundry list of expectations
• a map of your personality minefield
• a contract
• a stage on which to make a convincing performance as an inspirational leader
• just a bullet list. Please, please, please hear me on this – if your README is a bullet list, you don’t have a README yet. Let’s fix that.

So, why would I write a README, then?

Why do you value writing documentation about any project?

First, there’s a ton of value in thinking something through well enough to write it down. You intuitively sense this benefit, already. README Driven Development is a thing for a reason, after all, so there’s obviously a selfish benefit to be had. Starting from that intuition, then layering on the massive corpus of poorly written READMEs, it’s not hard to see how a few hot takes later the community sentiment turned into:

READMEs are bad, so don’t write one. If you absolutely must write one, for the love of God, keep it to yourself. You’re the only one it’s going to help.

This kind of pattern happens too frequently. Overwhelmed with potentially useful tools and information, we absorb the prevalent public sentiment, which is often an echo of words written by a few influential people, and make our decision once and forever – thing bad. We owe ourselves the kindness of revisiting those decisions from time to time.

READMEs are just a tool. Like any other tool, they aren’t inherently good or bad, but they are suited for some purposes better than others. And yes, self-development is one thing the README exercise is good for. But sometimes tools are good for more than one thing.

So, back to the question: Why do you value writing documentation about any project?

Well, yes, the project’s author benefits from writing documentation, but if the documentation isn’t shared, the benefits are limited. The real value emerges in the sharing, and the knowing the writing is for sharing. Let me explain.

A big part of writing project documentation is considering your audience. If the audience is you (especially present-day you) then that’s easy. You know, or at least think you know, yourself, and what you know about the project in question. Once you need to step outside of yourself, however, the story changes.The average person who happens upon your project likely needs more context, if they are to effectively collaborate on the project.

So you’ll want to write about the project’s purpose. You’ll want to explain what’s in scope and out of scope. You might share some performance characteristics and usage examples, and outline where those differ from the intended goals of the project.

You’ll help folks understand how to get involved. How to file issues, request changes, and otherwise deliver helpful feedback on what’s working and what’s not working. You’ll acknowledge known issues, perhaps explaining but not excusing them. You’ll be clear about what expectations they should have of the project, so they’ll know what’s a bug and what’s a design choice. You’ll explain design choices so they’ll know how to question them and advocate for possible improvements to the design.

If you do it well, you’ll kickstart a virtuous cycle of ongoing collaboration and improvements for everyone’s benefit, including your own.

Warning: Accountability Ahead

So, put in the work to write a thoughtful README and it will empower your team to challenge you, using your own words as the standard. I’m not going to sugar coat it: your team will expect more of you if you do this. You will let them down, sometimes. If you find that scary, it kind of is. But it’s also absolutely necessary.

This is probably not a huge surprise, but there are lots of managers out there who don’t want to, or don’t know how to, do the actual work of leading. Part of that work is being accountable.

I’ll let you in on an interviewing secret of mine. When I talk to prospective leaders, on either side of the interviewing table (metaphorical as it may be, in these Zoom-centric times), I’m looking for one thing: a philosphy of leadership rooted in some values we can align on. As I recently shared, values are one of the few tools folks have to hold leadership accountable.

To put it another way: leadership, like 8-ball, requires that you call your shots. I need to know what you’re going to do and – every bit as important – how you intend to do it. Far too many people are playing slop and getting away with it because they got a desirable result and confidently looked the part while doing it. “I totally meant to do that” is not leading. It’s luck. Wow, to be honest, I didn’t realize how well that analogy was going to work when I started typing it. See? You wouldn’t have known if I hadn’t told you.

Your README is where you call your shots. State your purpose and how you intend to accomplish it. You might miss on one or both of these. How you handle that will have a lot more impact on your credibility than any single miss will ever have, if you’re doing it right. If you set yourself up so that messing up, which is part of being human, will demolish your credibility, it’s time to ask whether you had any to begin with, or you were just buying into your own BS.

Call your shots, hit many of them, and be willing to own your mistakes when you don’t, and I guarantee you’ll change the expectations your team members have on every leader they work with after you. That’s how we change this industry for the better.

Can you just give me a template to follow?

No. There is no template, because for these things to work, they have to represent you. You as in actual-you, not fresh-from-a-management-seminar-you. “Authenticity” has been uttered to the point of semantic satiation, but I do believe we have an inbuilt sense for when someone is being authentic, and we never quite lose it when we grow up – we just sort of bury it. If you try to write what you think you should write instead of what is real, people will know you’re full of crap, even if they can’t quite explain how they know.

But here are a few things to consider as you write:

• It wouldn’t hurt to explain what the README’s purpose is – why did you write it, and what do you hope the reader gets out of it?
• Err on the side of writing more, not less. Add section headers for scannability.
• Seriously, lose the bullet points.
• The README is about you, not the reader, but is written for the benefit of the reader. Make sure to describe your purpose, expectations they can have of you, and any other characteristics that might be helpful. Make sure it accurately reflects you both in reality and in aspiration, and therefore contains things that you genuinely want to be held accountable for.
• Toward that end, it’s helpful to describe personality characteristics, but I would strongly suggest you don’t rely on your own powers of introspection, formidable as they may be. Might I suggest outsourcing that part to one of many personality and work style evaluation tools out there? I’m partial to the Riso-Hudson Enneagram Type Indicator, but since they all have some degree of pseudoscience around them, it’s better to just pick one and answer questions honestly, then reflect on what they tell you. Package that up in whatever makes sense for you and your team.
• Save any expectations you have of your team members for last. This doc is first and foremost an accountability framework for you. Consider the expectations you share carefully. They should serve them and their career growth, and not be a list of arbitrary rules for interacting with you.
• Remember that due to the nature of your job and the inherent power differential, when there is emotional labor to be done, you are the one to do it. Asking that of your team in interacting with you is abuse of power. Don’t do it.

If after reading this, you’ve decided to give another look at writing a Manager README, or look at your existing one with fresh eyes, I’m glad to hear it. I hope this gets you off to a good start, and I’d love to hear how it goes!

If not, well… Brandon, I finally delivered on that promise I made. ❤️