Should I write a Manager README?

White circle imageWhite circle image

Article Summary

  • Why should you read this: you may have heard about the manager README. People write them for differing purposes, but generally speaking it's a document created by a manager for a team member to explain some things they think would be useful to know about them before they start working together, having regular 1:1s, etc. You might even have been asked to put one together.  In theory they sound like a great idea.  In practice, they have a few problems you should be aware of before putting pen to paper.
  • The idea is compelling: when two people start working together there is often a period (it could be a while!) where mistakes are made because either side isn’t used to the others’ personality or preferred way of working.  Hopefully this is worked through and gradually trust is built, but this period can cause friction.  As a manager, what if you could skip all this by telling your team certain things ahead of time? How you want to communicate, what you value on a team, what you don’t, what success looks like etc.  Becoming a more effective manager is the ‘promise’ of a manager README document.  There are many examples online as they have become more popular, particular in the tech sector.
  • But there are issues: many people (one blog post in particular) have pointed out that there are problems with these documents.  They can come across as trying to shoehorn your team into your way of working, rather than appearing adaptable to their needs. Particularly if you use it to try and excuse poor management practices - e.g. saying ‘I know I can be difficult to work with’. Moreover, it takes remarkable self-perception to write a comprehensive list of ‘things you should know about me’ - you’re almost bound to miss/misrepresent something which will make you look either foolish or uncredible, depending how bad the mistake is. 
  • Also, writing is hard: even if you are very self-aware, it’s difficult to present these ideas clearly on paper.  Sentences such as ‘I value speed of delivery’ may be clear to you, but are very open to interpretation in different work contexts.  Similarly, you may think your README section on ‘My Philosophy of Leadership’ is great.  Others may think you sound like a pretentious jerk.  Whilst trying to get your thoughts on paper can be useful in and of itself, it may not be the best way to convey them to your team.
  • So should I write one? A lot of the issues with READMEs are in the delivery.  The practice of reflecting on what your team might want to know to work best with you is a good one (particularly if you sense-check your ideas with a trusted partner).  The problem is that most of us aren’t good enough written communicators to put that down on paper, and present it in a way which is authentic and helpful (if you are, go ahead!).  An alternative is to reflect, write, but introduce the ideas in conversation rather than a formal document. By giving the other person the opportunity to share their thoughts, ask questions and get additional context, you may create a more inclusive discussion which is less open to misinterpretation.

For more advice like this, check out our newsletter. You'll get regular practical tips and advice on how to build your team. For example, how to nail your first 1:1 meeting, how to talk about career goals, and more.

What is a Manager README?

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 - - 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.

Why a Manager README seems like a good idea

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, didn't take feedback well, missed a deadline without telling you, or didn't show up for a 1:1.  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, particularly if you're new to management.

So although they’re all different, if you review a bunch of Manager READMEs they tend to contain sections around: 

  • Personal history: details about your previous work history and life, and any lessons you learned, which might be helpful for your new hire to be aware of.
  • Communication: how you like to communicate, gather and share information; how you like to run certain meetings; when you’ll be available.
  • Performance management: how your company assesses performance; how feedback is given/collected;  how you’ll use 1:1 time.
  • Ways of working: what you prioritise day-to-day; your average week; how you see your role as a manager; what you expect from your team.
  • The first 90 days/6 months: what does success look like over someone’s initial period at the company.

(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. 

Why Manager READMEs can be a terrible idea

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.

Fournier Tweet
Source: Twitter

Her key points remain very valid: 

  • A damaging power dynamic: handing someone a document like this from a position of authority (which you are in) can feel like a diktat.  This is my way of working, which you need to fit into to succeed.  Not particularly inclusive or considerate of the employee. 

  • You don’t know yourself as well as you think you do: creating a document which authentically reflects how you work requires incredible self-perception which most of us don’t have.  We all have blind spots.  At best, you’ll create misaligned expectations, at worst you’ll come across as misguided and hypocritical when you inevitably do something which doesn’t match what you’ve written on the page.  If you write ‘I think it’s important that your evenings and weekends are your own’, are you definitely not going to message someone and expect a response? When you say, ‘I put people first’, do you actually? Or did you just think that phrase sounded good to other humans? You’ll get caught out.

  • It doesn’t excuse bad behaviour: some READMEs include sections on ‘flaws’ to be aware of - ‘I get heated in discussions’, ‘I can be hard to please’ etc which some managers interpret as license not to work to improve on those areas.  Just because you’ve told someone in advance that you can be a jerk, doesn’t mean it’s ok to be one.

  • Don’t rely on it to create trust:  it’s just a document, it can help, but it’s no replacement for actually doing the work together which builds a relationship.  As Fournier says, “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.” 

  • It’ll go out of date: people change, so do you.  These documents become irrelevant if you don’t update them, and too many people leave them static. 

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 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...

Splitting the ‘Why’, the ‘What’ and the ‘How’

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.

If you're looking for more practical tips on communicating effectively with your team, check out the Communication section of our Manager Guide.

Are You Ready?

Make Managing Simpler

try for free
White circle imageWhite circle image