One CEO described them as ‘the indispensable document for the modern manager’. One celebrated author on actually being a modern manager said they were ‘self-serving’ and that those who used them should ‘get the fuck over yourselves’.
So you can probably see this isn’t going to be an article with a simple yes/no answer.
Before we get into it, some of you will be asking what on earth a Manager README is? Or even a README at all for that matter.
A README is a text file included in the code repository of a software development project to introduce the project and explain how to use it. If that sounds like a weird thing to apply to a human or, dare we say it, a manager, congratulations, you’re on your way to spotting some of the pitfalls of these documents. But you can begin to see the intention.
Also sometimes called user guides or blueprints, a Manager README is a document put together by a manager for a new team member, explaining some of the things they think would be useful for that person to know about them before they start working together. The precise purpose will vary from manager to manager and team to team, but generally speaking, that's the idea.
As you can probably tell from the ‘README’ part, these documents have become popular in the tech sector over the past few years before proliferating elsewhere. We even came across examples where in certain companies all managers were encouraged to produce a README for their teams. There’s even a whole website - https://managerreadme.com/ - where you can write and share your own! This is, as they say, ‘a thing’.
You may have either been encouraged to produce a README by your company or are considering it independently. In which case, this article is for you. If we’ve just piqued your curiosity, then come along for the ride too.
FREE BONUS RESOURCE
If you're looking at putting together a README, we imagine you're thinking about ways you can be a better manager. Our checklist will give you some more ideas.
In theory, the idea of a Manager README is compelling.
(The ‘in theory’ bit is doing a lot of work here, as we’ll see later, but we’ll play along for now).
As managers, we’ve all been in situations where a new team member has done something out of keeping with how the rest of your team operates - because everyone else who’s been there longer just ‘knows how it’s done.’ Perhaps they didn’t copy you in on a certain email, or missed a deadline without telling you, or weren’t available for an important meeting. And it’s not just the negative stuff - perhaps they’re not taking all their paid time off, or don’t appreciate that you want feedback as their manager on what you can do better for them.
Wouldn’t it be great to just set certain expectations up front, without having to implicitly work out what both sides liked and disliked?
Similarly, as the team member, it can be incredibly frustrating to go through the process of working out how to best help your boss. As one customer told us when we were talking about the early days with their manager:
"They gave me no tools or set expectations for what they wanted to see… it meant i had to fuck up a lot, which was quite tough, and wasn’t particularly pleasant to work that way.”
The promise of the Manager README is to help you skip this phase and move faster towards doing great work together.
So although they’re all different, if you review a bunch of Manager READMEs they tend to contain sections around:
(We’re not going to recommend particular ‘good’ READMEs, but here’s a selection from an engineering leader at Apple, a Director of Engineering at Buffer and the CTO at Wealthsimple if you’re interested. You can find many more online).
At this point, getting a lot of that stuff understood by both parties seems incredibly helpful. Hold that thought.
In late 2018, as the idea of Manager READMEs was gaining traction, Camille Fournier, author of the Manager’s Path, came out forcefully against them in a series of tweets and a medium post. She did not mince her words.
Her key points remain very valid:
To all these points, we’d add a further one that putting these types of thoughts on paper is really unforgiving. Writing well is hard (we’ve mentioned this before). This means it can be difficult to get your meaning across, and in some cases you can give the wrong impression to your audience.
For example, we’ve seen READMEs where ‘Speed’ is listed as something someone ‘values’ above all else. Without additional context, it’s really hard to know how to implement that in day-to-day work.
Then there’s the language you use. For example, we’ve seen a few examples which talk about people’s ‘Philosophy of Work’. Some team members might respond well to that. Others (*raises hand), might think you’re not bloody Nietzsche and you need to get off your high horse. It’s tricky.
That's not to say that trying to get your thoughts down on paper isn't useful - it can be very helpful to clarify your thinking. But depending on your writing style, it may not be the best way to convey them to your team.
Ok so that’s that then. READMEs - nice in theory, terrible in practice. Well, not quite...
If we go back to the start, the original intention of the README is a good one: are there things it would be useful to communicate to new team members so we can start working well together? Hard to argue with the ‘why’.
Also tricky to argue with the ‘what’. Reflecting on what those things are could also be a very useful exercise. Fournier even agrees with this!
“You know where these kinds of docs are useful? As a coaching, therapy, or personal introspection exercise! I love doing stuff like this for myself. It’s great to spend time writing down things that you believe about yourself.”
Particularly if you have someone you trust to check your assumptions and make sure you’re not creating an unrealistic picture.
Most of the problems with Manager READMEs seem to be in the ‘How’. Having reflected on these things which it would be useful for team members to know, what should a manager do with that information? Should they communicate it?
As explained above, trying to write it down in a document is a lot harder than it sounds, and is fraught with issues of misalignment and misinterpretation. However, if you are an outstanding written communicator, very confident in the thoughts you’re expressing, and believe you can present it in a constructive way, then by all means go for it. A written README could be a very valuable tool for you and your team.
Spoiler: most of us are not that person. It’s why company policies which stipulate all managers produce a README are, frankly, bizarre.
Instead, using your reflections as the basis for a series of conversations with a team member about setting expectations is probably a better way to go. By giving the other person the opportunity to share their thoughts, ask questions, and get additional context, you create a more inclusive discussion which is less open to misinterpretation. Others have reached the same conclusion.
So should you write a manager README? Sure, if you think it could help.
Should you talk to your team about some of your reflections? Probably a good idea.
Should you actually share it with your team? Think carefully.
Sign up for our newsletter to read our articles first. Join readers from Peloton, Facebook, Grab, CircleCI, and more...
FREE BONUS RESOURCE
We’ve compiled a list of questions you can ask your managers and team members to identify the challenges they face, and help you pick the right solutions.