README. An Owner’s Manual for your Manager.

README files are the first thing we all look at when working with a new code base. A good README helps you hit the ground running, and often help you understand the principles behind the code base so you know how to best work with it.

The idea behind a Manager’s README is the same. Like an owner’s manual for a manager, it gives the reader a recipe for how to best work with you.

Manager READMEs have gained a bit of traction recently with managers from Netflix, Slack, Etsy and Shopify using them. Like all popular things, they have also attracted their fair share of controversy.

In this talk Colin Chauvet share how he introduced Manager READMEs at Atlassian. What worked, what didn’t, how to get started and how to avoid coming across as a self-serving jerk!

(playful music) (applause) – Thanks Jana, hi everybody.

Today I’d like to start by telling you a story. I’m gonna tell you the story about the time I really wish my manager had written his manager README. So I joined Atlassian seven years ago as a developer. And Atlassian is a great company, but my first three months there, they were the most awful of my career.

I had a severe case of imposter syndrome.

I was convinced that they made a mistake by hiring me, and I was convinced that everyday was going to be my last. It sounds dramatic, but I was sure I was never gonna pass my probation period.

And that was in part due to the fact that I wasn’t getting any feedback from my manager. And I assumed that no feedback meant that I was in trouble. And until one day I summoned all my courage and I talked to my manager and I asked for feedback. And I’ll always remember that one on one, where he looked at me and said; Mate, he was Australian, so Australian accent. Mate, you’re doing awesome.

You’re one of the best new hire we’ve ever had. What makes you feel so insecure? And I was shocked, and I was really shocked. What I was expecting terrible news, and he was actually telling me I was doing okay. But as I was processing that, he continued and said, I should have told you that that’s just my style.

I don’t give positive feedback.

All right, with me, no news is good news.

I was like okay, that’s cool, that’s good to know. And I worked with that manager for a few years, and I learned more things about that person. For example I learned that he saw his role as a coach, not a doer.

And so if I, when I came to him with questions, he would answer my questions with more questions, leaving me frustrated because that wasn’t how my previous manager did it.

But he made it very clear that he wasn’t going to solve my problems for me.

If I came to him, if I was assigned with a new task and I came to him for advice and directions, he would typically send me back to my desk, and ask me to think about three possible solutions to that problem.

And come back when I had that so we can spar. Made it very clear again, don’t come to me if you haven’t thought deeply about the problem. Do your homework first.

I also learned that, that particular manager hated to repeat himself.

I learned to pay a lot of attention when he was talking because I knew that if I missed something, if I ask him questions later on, that would piss him off. And so in other words, over those many years I sort of learned a set of tips to work with that manager. I learned about how he liked to give feedback. I learned how he saw his role as my manager. And I learned about his expectations from me as a dev in his team.

And finally I learned about his personality and his quirks. And that set of tips, it really helped me create a strong, healthy relationship with that manager. And we ended up working together for many years, until one day he decided to take a sabbatical leave, and start his own brewery company.

And I was asked to step in as the manager for the team. And I was super excited, right.

I was really ecstatic about the role.

But I really struggled, I really struggled to build trust with my ex teammates, and I was now their manager. And part of that was due to the fact that all my teammates, they were still working under those rules.

They were still operating as if I was the old manager. Because like me, they had spent many months, many years, trying to work out how to best work with that team lead.

And the issue was that those rules, they weren’t my rules. I didn’t write them, they didn’t work for me. And that got me thinking as to whether I could find a tool that I could use to communicate how to best work with me, and how to build trust faster.

And that’s how I found about manager README’s. Today I’ll talk about what a manager README is. About why you might wanna write one for yourself. I’ll go for the mistakes I made when I wrote my first. And I’ll share some tips on how to write a good one. And we’ll wrap it up with the conclusion.

Okay, so what is that manager README thing? You’re probably all ex-developers, so you know what a README note code file in a code base is. It’s usually the first file you open when you start a new project.

And it’s supposed to be a short document which gets you orientated, and you know where to go, and you know how to run the test and all that stuff. And there’s many README’s around, I pulled this one from work I did yesterday, but a good README is; they always share the same attributes.

They always start by telling you what problem that code base is trying to solve. Then they’ll tell you about the guiding principles, what did the office have in mind when they wrote that code base? And usually that helps you work with that code base, and not against it.

One of the main purpose is to hit the ground running, right, they’ll tell you how to compile the code, how to run the test, how to run everything locally. If it’s an open source project, often they’ll tell you about how to contribute back. What’s the pull request, what are the standards. And the really good ones, they’ll tell you where the bodies are buried.

They’ll tell you about that package which is deep in the code base, that is a bit of mess, we should have refacted it ages ago, but we never got the chance to.

A manager README is essentially the same thing, but it’s for you, for humans.

Simply put, it’s your user manual.

It’s a document that you write to bootstrap the relationship between you and the people who work with you. And that might sound a bit weird at first, because we’re all familiar with README’s in code base, but README for humans, that can sound a bit strange. So where do you start? One thing I found is that there’s a nice power between the README of the code base and the README for human. First, you want to start by telling your team about your role.

What is your role as a manager? What is your responsibility? Then, you will want to tell your team about your guiding principles.

What are the things that you value more than others? Is it risk taking? Is it hitting deadline? Is it creativity? Then, how to communicate with you.

Is it okay to send you a Slack message anytime? Is it okay to book you for a meeting anytime? Emails? What works for you? In code we sort of send each other pull requests, but in human relationships, we give each other feedback.

So how do you like to give and receive feedback? What works for you? Is no news good news, like my old manager? Will we have one-on-one’s? What will we talk about during our one-on-one’s? And finally, what are your quirks? What about your personality? What are the things that you react very badly to? Okay, so now you have a sense of what a README for a human is.

But why, why would you bother? Let me give you three reasons.

The first one, and I can guarantee that by writing your README, you will learn something about yourself.

The simple fact of just getting a cup of coffee and sitting down with a blank page and thinking about your style of management, that’s useful for any kind of manager, no matter how long you’ve been doing it. Let’s face it, most of us fall into management by accident. Perhaps, like me, your manager went on leave and you were asked to step in.

The chances are you never had any formal training, and you learned sort of as you went.

And so, the simple act of really thinking about those questions; what is important to me? What drives me? Why do I come to work every day? How do I define my role as a manager? What is my responsibility, and what is the responsibility of the people in my team? What triggers me? What are the things I react really badly to? And finally, how do I like to give and receive feedback? And you really want to know the answers to all those questions, because chances are you’ve been operating from a set of rules, internal rules, subconscious. But you never had a chance to sit down, think about them, and validate them, and maybe challenge them. For me, for example, I had the image of myself as being a very cool, laid back, relaxed manager.

And then I wrote my README.

And I listed all the things that annoyed me; people who are late to meetings, people with their laptop open in meetings, people who ignore me on Slack. The list went on and on and on.

I was like, you know what? I’m actually not laid back at all.

And that was helpful to me.

That’s the first reason why I really recommend you write a README, even if you burn it afterwards. You don’t even have to share it.

The second reason why you might want to write a README is to build trust faster than you could through normal day-to-day interactions.

And by doing that, that will kickstart the relationship between you and the people in your team. So we talked about trust a lot today, and trust is a key component in any relationship. I would, it’s probably the most important element of any relationship.

And you know how sometimes we say of someone that we know well that we can read them as an open book? Well, your README is the first page of your book. By writing your README you are telling your team two things; you’re telling them first, I won’t play games. I won’t lie, I’ll be honest with you, this is me, full transparency.

And second, I want our relationship to be great. This is my manual, you have the keys to how I operate. Let’s do some great work together.

Building trust is always going to take time, and README’s are not a silver bullet.

But a good README will get you started on the right foot. It will help you get you to that place of mutual trust faster.

Which takes me to my third reason, and perhaps the most important.

README will help you share expectations, and reduce anxiety.

Let’s face it, we all create (mumbles) of biases. We all value some things more than others, and there’s nothing wrong with that.

But as the manager, the relationship between you and the people in your team is very asymmetric.

Because you’re the manager, you’re gonna write the performance review at the end of the year.

You have that power, and when you do assess the people in your team, you will do that in line with your biases, whether you like it or not, because that’s what biases are. And if your biases are gonna play a role in the performance review, then they have the right to know about them upfront, it’s as simple as that, it’s only fair. Maybe you’re the kind of manager who loves risk taking, for example.

If your team knows that, then it won’t hesitate to jump on that high risk, high reward project.

High potential reward, but high chance of failure. But maybe you’re the more risk averse type. And you think for your team it’s better to play it safe. If the people in your team don’t know which manager you are, then it’s as if you are letting them play a game, and not telling them about the rules until the very end. And that’s a recipe for frustration for everybody involved. One thing we tend to forget as well when we’ve been in our roles for a while is that when people join your team, they’ll go through a lot of doubt and anxiety during their first weeks, and this is what their inner voice might sound like during that time; Oh my god, I’m an imposter – happened to me. I’m not quite sure what my role is in this team, but I’m not sure if I should ask.

And if I do ask, will my manager think less of me? And anyway, none of that matters because my manager is always in meetings, she probably does not have time for me. Now all those questions, they can easily be addressed by a good README.

Imagine if that person received the following guidance on their first day; imposter syndrome is common here, don’t worry, you belong. As a developer on my team, your role is to do A, B, and C. I am here to help, I expect you to have plenty of questions, it’s okay, send them to me via Slack.

And my calendar might look scary, but feel free to book me for a meeting anytime. Now all those answers, they will go a long way into diffusing that anxiety that your teammate might feel. So I didn’t invent manager README, they’ve been around for a while, but they really took off in the past couple of years, with many prominent, well respected leaders writing their own.

People like Michael Lopp, which we all know which we all know is Rands, has his great How to Rands page on his website.

Fun fact about that, he actually stores it on GitHub and people on his team gets him a pull request if it is agreeing.

And plenty of tech blogs have published this type of article, this type of blog we’re listing some good examples of README’s.

But as an answer, there’s even a website called managerreadme.com, which is dedicated to manager README’s, where you can go and store or search for README’s, and that’s where I store mine.

But as README’s became very popular, we saw a little bit of controversy.

We saw a lot of blog posts that were against README’s, or tweets, they all came from equally well respected leaders.

Those are a few of them.

And when you read those blog posts, they make some very good points.

I find that the bulk of the criticism can really be boiled down to the three mistakes that people tend to make when they write their README’s. And turns out, I made all those mistakes, so I’ll go through them right now.

The first mistake is to create more anxiety. Remember how I said earlier that in a section of my README I listed all the things that irritated me? Being late to meeting, having your laptop open, ignoring me on Slack, and so on and so forth, gossiping, there’s a long list like that.

And I really though that it would be useful for my team to know about them.

But remember we said that the number one reason to write a README is to reduce anxiety.

Imagine you just joined my team and I shared my README with you, and the first thing you learned about me is that long list of things that you should not say, or should not do if you are around me.

What does that do to your stress levels? I mean, when I read this, I don’t want to work with this guy, and that guy is me.

The truth is that you have to find the right balance between being open and honest, but at the same time, being welcoming and approachable.

So, yes, list of things that you really care about, but don’t list all your pet peeves.

Okay, mistake number two I call it the stone tablet. When I wrote my README a couple of years ago, it took a fairly long time to write it, and then I started sharing it with the world. But until very recently, I never updated it. And that’s because I thought that it should be a static document.

After all, I did a lot of introspection, I talked about my core values, and those are not supposed to change every day. And so, I really treated my README as a stone tablet. Something that you take a lot of time to write, but then you never change it.

And I was wrong, I realise now that I was completely wrong, because I’m not the same manager I was six months ago. And I hope I’ll be a different manager in six months as I learn and I grow.

And to understand the impact of that mistake, think back to your coding days.

Think about the last time you worked on a code base, and you realised maybe after a few hours, that the README you were reading was completely out of date. And it was telling you the wrong instructions. That’s frustrating when you’re trying to get the test to run.

So imagine how worse that is when you’re new to a team and you’re trying to work out how to work with your manager. And that takes me to my third mistake, and by far my biggest mistake, and I call it the candy store. Writing is difficult, I think we all know that. Writing about yourself, being vulnerable, being open, that can be terrifying.

And so, where do you start? Again, remember, go back to your coding days, when you had to solve a problem for the first time. What did you do? Stack overflow, exactly right.

You would Google the problem, you would find a code snippet which looked good, you would change it ever so slightly, and you will paste it back in your code base.

And that’s pretty much ingrained in how we solve problem. So it’s very tempting to do the same thing when you write your manager README.

As I said, they’re very popular, it’s easy to Google best manager README, and you’ll find plenty of things. Now, the next slide is a picture of me doing just that. I was exactly that little girl.

I was a kid in a candy store.

I was looking at all those manager README’s out there, and they said things like servant leadership, we’re talking about that, democrative leadership. They said things like I want to be responsive, but not intrusive.

They even rhymed.

I was amazed, I was mesmerised, and said I’d like some of that, some of that, some of that.

And I copy and pasted a bunch of that.

But your README, it should be about you.

It should be about the kind of manager you are today, not the kind of manager you want to be in five years. It should be accurate, not aspirational, and that’s crucial. Because if you oversell yourself, if you say that you are this awesome, flawless manager, then you are setting yourself up for failure. Because what happens when you start behaving in a way that contradicts your README? That will damage your credibility hard.

All that trust that you have built day in and day out with your team will go by the window.

Because if you’re lying on your README, then why should I trust you? Why should I believe you? For me, in my README, at the bottom I had a section that said; if you see me behave in a way that contradicts my README, please call it out.

I love feedback.

Do you know how many people called me out in two years? Exactly right, zero.

No one did it.

And of course no one did it, I mean, can you imagine having that conversation with your manager? Colin, you said in your README that you don’t like when people gossip, but yesterday at lunch you spent your entire lunch talking shit about Jeff from platforms, so does that make you a hypocrite? It’s a pretty difficult conversation to have. The other thing that you’ll notice when you start looking at README’s is that they all look very similar. That README over there, that manager talks about feedback and makes the case that good feedback is made of safety, effort, and benefit.

And that sounds pretty good, so good in fact that that other manager thinks exactly the same thing.

So does this one, and so does this one.

So maybe that’s a coincidence, so I kept looking what else the manager really like. They like work/life balance, and they are all quote big on work/life balance, end quote.

All of them, they don’t even change the text, it’s a straight copy and paste.

And it would be quite easy for me to stand there and sort of make fun of those managers.

I won’t do that, because that manager README is mine. I made that mistake.

Sounded good, so I copy and pasted it.

Okay, so, so far we talked about how not to write a README. But let me share a few tips on how to write a good one. First tip, start from a blank page.

You must avoid the candy store.

I know it’s difficult, we don’t like doing that, but you must in this case.

Start with a blank page, get a cup of coffee, and ask yourself those questions.

What is my role as a manager? What can people expect from me, and what do I expect from my team? What is important to me? What do I value more than the rest? Is it hitting deadline? Is it taking risks? Is it customer impact? Is it creativity? Whatever that is for you.

What’s the best way to communicate with me? What’s my protocol? Is it okay to send me Slack messages at any time of the day or the night? Maybe it is, maybe it isn’t.

And then optionally, what are your quirks? Don’t be too direct there, though.

Then my second tip is to ask for early and honest reviews. It’s kind of like when you are writing a code. You typically don’t push your first coding straight to production.

You want to get some feedback on it, and being self-aware is quite difficult, so it’s important to get that feedback. The first person you should share your draught with is your manager, your own manager.

You don’t want that document to be a surprise to them. They might have a different view on how you should lead your team, and that could be very awkward if there’s a conflict there.

Then, share it with a peer who knows you well. Someone who doesn’t report to you, someone you trust, and someone who will feel safe to challenge or give you some critical feedback.

And then finally, before broadcasting it to your whole team, pick that one person in the team that reports to you, but maybe you’ve worked with that person for a very long time and you have a great relationship, and they can give you some feedback.

And my third tip is to keep your README updated. As we talked about, it’s a living document, not a stone tablet.

And and outdated manager README will do more harm than good. Some tips on how to keep your README updated; an easy way is to set a recurring calendar invite with yourself.

You know, to refresh your README every three months or so. If your team is in a growth phase, then what you can do is use every new hire as a trigger to refresh it. And when you do change it, remember to communicate the changes back to your team. Don’t assume that they’re just gonna find out about it. What did you change? Why? Did you change what’s important to you? Did you change your expectations from the people in your team? Chances are, they will need to know those changes. So use some time in your one-on-one’s to talk about that. Okay, let’s wrap it up.

Hopefully by this point of the talk, I’ve piqued your curiosity and maybe you want to give manager README a go. And I really do recommend that you give it a shot, even if you don’t share it with anyone.

If you do share it with your team, though, which I really recommend, why not take it to the next level? Why not ask the people in your team to write their own README’s intended for you? So that you can tailor your style to match theirs. Because it shouldn’t be a one-way thing, all the burden of adaptation shouldn’t rest on them. We all different and we all unique, but I really believe that if we can be open and honest with each other, and build high quality, high trust relationships from the get go, that will set your team up for success. Thank you very much.

(applause) (playful music)

Join the conversation!

Your email address will not be published. Required fields are marked *

No comment yet.