Some software engineering managers swear by a tool called a Manager README.
It takes a concept already familiar to most developers — the README file — but instead of describing how to work with a particular codebase, the Manager README describes how to work with a particular manager.
Just as a standard README file will orient you and cover the basics, but is no substitute for becoming familiar with the codebase itself, a Manager README is not intended as a substitute for actual engagement between a manager and their reports. Rather, it's supposed to serve as a starting point, and a place of reference to which both the manager and their reports can refer back when needed.
Why convey this information in a README rather than delivering it verbally during an introductory 1:1? Isn't the latter a more personable approach?
Many managers who use READMEs do, in fact, deliver the same information during a 1:1 meeting. Some will pull up the document and walk through it during an intro meeting with new hires, while others will communicate essentially the same content, but in a more conversational way.
But a benefit of also sharing the content in written form is that it's a persistent document, so both the manager and reports can return to it later. It also helps ensure that all of their reports have equal access to the same information.
Proponents of the Manager README emphasize that it shouldn't substitute for personal interaction or be viewed as primarily a time-saving device, because regardless of how well written it is, a README is not going to establish a relationship. The manager still has to put in the effort. But it can help guide the conversation and serve as a tool that promotes accountability.
When composed thoughtfully and used prudently, a Manager README can contribute to the onboarding process and serve as a continuing touchstone as a manager and their reports grow in their working relationship.
But is a README file really the best metaphor to use here?
Normally, when a developer encounters a README file, it's presented as a one-way flow of solidified information.
And if you look at some examples of Manager READMEs disseminated online, you'll notice that many of them have a similar vibe: This is who I am. Here's how I prefer to do things. Here's how to work with me. Here's how to deal with my idiosycrasies.
There is a seed of empathy here, insofar as the authors seem to understand that establishing a working relationship with a new manager can be difficult, and they want to make it less difficult.
But describing things in terms of "Here are my preferences" and "Here's how to deal with me" is a passive-aggressive form of empathy. The implicit message is that, in the words of Popeye, "I yam what I yam" — and it's you who needs to conform your approach to me, not the other way around. But because I yam such a considerate manager, I've provided you with a guide that teaches you how to do it.
Nevermind the power asymmetry here. Is that really a good way to kick off any relationship, personal or professional?
Some managers may object and say I'm criticizing a straw-man version of the tool, one that's written by someone who doesn't fully understand its purpose.
But I'd argue this is a fundamental problem with any version of a Manager README. You might not intend for your reports to interpret your document as a way for you to hint at whose preferences matter most in this working relationship. But if you're the one filling out their performance evaluations, you can bet it will cross their mind.
Is there any other concept familiar to most programmers that is similar to a README but avoids some of these issues?
One possibility is a WIP PR — a work-in-progress pull request. Developers who use git for version control create pull requests (aka merge requests) when they're ready to have their code reviewed. But sometimes it can be useful to solicit early feedback while the code is still a work in progress, with the understanding that things are still in flux, not set in stone.
Whereas a README implies a one-way flow of solidified information, a WIP PR implies a collaborative, evolving document for which the manager is soliciting feedback. Using this metaphor connotes a kick-off of a conversation, rather than the conferral of a handbook.
Another potential metaphor is a working agreement. While these documents are typically used by software teams to establish norms and expectations by mutual consent, there's no reason a manager and each of his or her direct reports couldn't have their own version of a working agreement. The "agreement" part is key. The less unilateral it feels, the better.
How might these other metaphors work in practice? The whole point of a README is that it's a static text file that can easily be passed around, such as in a welcome email for new hires. What would you do to emulate a WIP PR? Post something on GitHub and solicit comments? And how would you put together a working agreement if you don't know who you'll be working with?
One possibility, which I'll borrow from the world of marriage prep, is for both manager and report to complete a questionnaire about common preferences and expectations — how you each like getting feedback, what expectations you each have about a manager's role, and what working styles you each have — and then meet to go over your answers together.
Does such a questionnaire cover essentially the same topics as in a Manager README? Yes. But notice how a format like this puts the manager and their report on roughly equal footing. No one's preferences are pre-empted by the other person's, because you're both revealing them at the same time.
Frankly, the best managers likely take it a step further and acknowledge that not only should their preferences and foibles not take precedence (as with a Manager README), but they shouldn't even be on equal footing. A great manager should invest the time to learn about each of the people who report to them and what management approach brings out the best in them, then personalize their approach for each report.
For instance, what do I, as a manager, think about 1:1s? A Manager README might tell you. But what do you, as the person I manage, think about 1:1s? That's the much more important consideration.
I hope you'll consider some of the alternate metaphors and approaches I've just described in lieu of a Manager README.
But because of their popularity, I wouldn't expect them to die out any time soon, and some engineering organizations may require their managers to compose a README. If you don't have the liberty to use a different tool, then at least you can take a different approach with the tool.
First, write a Manager README in the traditional form, detailing the duties of your role, your work preferences, management philosophy, personality quirks, and values. This can be a great exercise in introspection.
Now file that version away in a desk drawer. If it's helpful, reflect on it from time to time. But don't share it with anybody who reports to you.
Instead, create a new version that is not presented as a user manual or anything focused on you.
Instead, it should focus on the reader, the person you'll be managing. Ideally, the content should be almost exclusively interrogative rather than declarative. What are their working preferences and values? What motivates them? What do they appreciate in a manager?
Ultimately, while it's important for your reports to understand who you are, it's even more important that you understand who they are — and by prioritizing the gathering of that information, you're putting into action a management competency that your reports will derive more benefits than from a user manual.
Shaun Gallagher is the author of three popular science books and one silly statistics book:
He's also a software engineering manager and lives in northern Delaware with his wife and children.
Visit his portfolio site for more about his books and his programming projects.
The views expressed on this blog are his own and do not necessarily represent the views of his publishers or employer.
Adapted from a 2020 study, this web experiment tests a cognitive quirk that contributes to dogmatic worldviews.
This student guide explores three economic systems (capitalism, socialism, and distributism) and explains how distributism is different from the other two.
What if making money is not one of your top goals? And what if you happen to stumble into a high-paying career nonetheless?
How to build up and encourage code authors during the review process
A poem about all the rules you can break — and the one rule you can't.