The Manager README is dead — introducing the Manager README

Trev de Vroome
3 min readOct 16, 2019

A history lesson: The Manager README

It’s unclear who and when the first Manager README truly came to fruition, although the earliest popularisation appears to be stemming from Luc Levesque back in 2012 ¹.

For User Manuals, it’s origins are a little less clear — with the first known mention being a NY Times article² interviewing Ivon Kroghrud back in 2013 where he introduced his User Manual. This has since been followed by a series of popularisation articles over the years.

In either case — both documents were set out to establish a common understanding between the staff and the line manager on expectations, values, norms, and quirks — and have had substantial momentum in tech leadership since Roy Rapoport released his README public while working at Netflix back in 2016.

While many new leaders are using these tools to drive engagement with their teams, there is no clear and common understanding on what they aim to achieve by setting expectations with their staff, and how these truly contribute to that effect.

The question remains — are they the tool we should be using as leaders?

The good, the bad, and the misunderstood

I deeply sympathise with the broader community on the misuse of these tools. The highlight being Camille Fournier and her great article on why she hates these documents — with her closing comment capturing the overlooked absurdity that comes with manager READMEs:

You’re probably just wasting your time, because no one reads the docs anyway!

Many a manager has hidden behind a README to mask broader problems of being time-poor, not valuing face to face communication, or worse — running their staff through their quirks expecting it gives them some leeway when they behave in that manner — similar to the concerns I (and others) have with The Core Protocols.

In each case, we’re forgetting the core of what we strive to achieve in our never-ending pursuit to be more Agile, the values and principles that should underpin our behaviour.

Providing a defined list of expectations to a staff member doesn’t sound at all like our value of…

“customer collaboration over contract negotiation”

Sending that new starter a slide deck for them to read through doesn’t at all drive home that you’re embodying the principle of…

“the most efficient & effective method of conveying information… is face to face communication”

Nor does asking your staff to edit the document to provide updates and feedback to you show that you care about having…

“at regular intervals, the team reflects on how to become more effective, then tunes and adjusts its behaviour accordingly.”

In jumping on this bandwagon, we’ve forgotten all about the values and principles we hold dear — a common leadership trait that many of us struggle with.

So how wrong was the Manager README?

The Manager README was never a bad idea, it was always just misused. Somewhere along our path, we forgot that introspection is a tool is for you, and not for your team.

Sitting down with a Manager README is a great thing to do as a leader to introspect — really reflecting on deep questions like:

  • Who am I?
  • What do I value?
  • What are my commitments to my team and the business?
  • How do I want others to engage with me?
  • What are my strengths/weaknesses?
  • What do my team expect of me?
  • What do I expect of my team?

However, this needs to be used as a tool to think about expectations. If you need to write this down, then so be it — but we should aim to never provide this information to our team via a document.

Instead — for aligning with your team on values and norms, you need a conversation³ to drive shared understanding. Drawing forth your self-awareness on those assumptions, values, and artifacts through shared stories, and not via doctrine, documents, and published materials.

Use the Manager README as introspection — for shared understanding, use an Incremental Growth Model driven by conversation, stories, and regular inspection and adaption.


  1. Kloppenburg. S (2019), Manager-READMEs, Github (svnk)
  2. Bryant. A (2013), Want to know me? Just read my user manual, NY Times
  3. Jeffries. R (2001), Essential XP: Card, Conversation, Confirmation,



Trev de Vroome

Information technology program and agile transformation leader, change catalyst, and educator.