Why I stopped using Manager READMEs and no longer recommend them

It’s been over a year since I wrote about my version of Manager READMEs and it’s been great to see READMEs and discussions about them crop up all over the internet. I shared some tips about successfully sharing information through documents on Twitter and here I’ll apply them to a Manager README to help you avoid some common pitfalls that can lead the document to hurt more than it helps.

As a reminder, my intent of a Manager README had two parts:

1. Share expectations
2. Build trust

A year later, I think it’s better to focus on the recipient’s value of this document, hence this new and improved intent:

1. Share expectations to reduce their anxiety
2. Build trust as they get to know you

It helps to have this intent as a guide when you’re assembling and editing your document. Some folks use the North Star as their guiding landmark metaphor, but I’m going to use this oak tree because I love it.

Our goal is to provide soothing context to the people with whom we work. Here are a few things that you must do as part of the README delivery to succeed:

• Iterate on the document before you send it, gathering feedback along the way;
• Treat the document as one piece of a multi-pronged communication strategy; and
• Keep the document alive and refer back to it.

Let’s break down each of these in order to get you closer to success.

You can’t measure successful communication by yourself.

This is a document like any other which means you need to iterate on it before sending it out. If you don’t have much experience with this, here is a short list of suggested folks to add to your editing crew:

• A peer who knows you. They don’t have to work with you, but they should be able to recognize if your README is in your voice and if it is accurately conveying what you intend.
• One or two of the intended recipients; one is good, two is better if you have highly divergent personalities among your recipients.
• Your manager. You don’t want this context to be a surprise to them in case they expect something different of your team.

If you’re really not comfortable talking to these people at work, you can also talk to strangers on the internet. There are various communities (rands leadership, software leads weekly, managerreadme.com) who can help you know if your intention is coming across and also if the tone is friendly and inviting or aggressive and combative.

As a reminder, the purpose of this document is to provide enough context about working in your ecosystem to reduce their anxiety; you want to avoid sounding aggressive here. You also want to steer away from distracting content: your aspirations, flaws you’re trying to correct, and anything that doesn’t explicitly help your audience reduce their stress as they begin this relationship with you. Sharing your personal goals with your team is a terrific thing to do, but save that for another time. The tone of your README is especially important if you share it on the internet to be judged by potential future employers and peers.

Only after you’ve received feedback that you’ve successfully communicated the message you intended, and you’ve confirmed your message doesn’t make you look like a jerk (self-serving, out of touch, attention-seeking, unprofessional, or other like qualities), will you be a step closer to success.

Documents are necessary but not sufficient.

There are a few ways to use a Manager README: as an onboarding tool for new team-members, as an onboarding tool when you’re new, and as a way to verify team expectations. It’s valuable to write these things down in addition to having 1-1 conversations. Some people process information more easily visually, and for most new folks on the team they’ll have a firehose of information and will want to refer back to it. In any use case, it’s not acceptable to send a document with a comment reading “RTFM, kthxbye” and expect them to fend for themselves.

Develop a multi-platform communication strategy including your README, 1-1 conversation, and possibly a group conversation with your team. The point of this strategy is singular: you need to ensure that you and your audience have a common understanding of your content.

You’ll also want to frame these conversations appropriately. Don’t just dump this document on your team citing, “I read this thing on hackernews, here you go!” Talk to them about your intentions so that they can better understand if engaging with you on this topic is worth it for them. If your team isn’t into it, they may not agree about the value and it’s not going to help you succeed.

With the proper set-up and follow-through, you’ll be a little closer to success.

Context changes, so context-setting documents should too.

You’ve iterated on your README until you’re pretty sure that it will be received well. You shared the document and then discussed it with its recipients, answering questions and closing any information gaps until you’re all well aligned. Are you done now? Nope!

Things will change over time, and your README should change too. You can handle this in myriad ways. You can distribute copies of your README as new folks join, updating as each person joins and sharing the updates with the rest of the team. You can refer back to your README in team meetings and discuss how things are changing as you see it. You can incorporate aspects into your overall team on-boarding documents and let those update organically. It doesn’t matter what document organization system you use, so long as changes are documented and understood.

If your README becomes static, nobody will refer back to it and as your behavior diverges from the README it will no longer be a trustworthy source. You’re allowed to change what you want over time – I encourage it – but if you’re not communicating those changes well, you won’t get the results you’re looking for.

Communicate the change you want to see in an ongoing fashion and you’ll continue to help reduce stress on your team and keep you headed in the right direction to a successfully delivered README.

Summary

Manager READMEs are intended to share context in order to reduce the anxiety produced by not having information.

To be successful, you need to do the following on top of coming up with your content:

• Iterate on the document before you send it, gathering feedback along the way,
• Treat the document as one piece of a multi-pronged communication strategy, and
• Keep the document alive and refer back to it.

I hope this helps bring you closer to your team; let me know how it goes!

Want to learn more about Manager READMEs? Check out my earlier post and my conversation with Corey Quinn on Screaming in the Cloud!