I’ve heard that manager READMEs are bad . The criticism revolves around these documents ultimately being self serving by giving the author a way to justify acting in the wrong. For example, if I write in my README that “I don’t handle criticism well” and I explode when someone says I’m wrong, I’m OK because I said it up front. Camille Fournier made the point that people should just do the work and fix their issues rather than putting it on our teams to deal with our faults. I’ve also read that writing a “user manual” can be really helpful to a team . When I watched Michael Lopp’s “How to Rands” talk from Calibrate , the value of a README or User Manual made more sense.
The context that makes these documents work for some teams is:
- The README is used as a living document to help hold each other accountable on problem areas.
- The README is referenced when providing feedback or helping someone correct behavior.
In this context, a README provides some structure for establishing empathy. Assuming the author has done some actual soul searching and worked to communicate the findings, I can easily imagine how a team would benefit from this exercise. And “team” is the operative word here. If a manager keeps this sort of document around and prescribes it to people, many of the criticisms seem valid. Giving someone you have no relationship with a document outlining how they should be working with you feels selfish and lazy. Some manager writing down a few snippets from Amazon Core Values does not convey to me anything other than this person is self seeking and does not have my best interest in mind when making decisions.
To contrast this, I can imagine a team getting together for an offsite and going through the exercise of writing up a README. I’ve been to a few already that effectively do this by asking question such as “what is something that no one here knows about you?” or “what would you do if money wasn’t an object?” These sorts of questions are there to help you understand where you team mates are coming from in the hopes that you can glean some understanding when there are disagreements. I can say first hand that after doing these sorts of exercises with team members, Slack changes radically because I know the people better. The short statements that seem curt often become meaningful because I know the backstory. When I think about writing a README, it seems like a good deliverable or artifact from these team building exercises that can help codify the self reflection process, provide a cadence for review (bi-annual off-sites) and help create a team culture that focuses on empathy through knowing each other on the team.
Like everything, “it depends” is certainly true here. If your team doesn’t have a leader that is driving this approach to understanding each other, I can’t imagine it would be successful. As someone that is trying to be a leader, I’ll likely give it a try at some point, with the caveat that my own intended usage is just a tool. Those that argue it is a pathway to trust within teams or an effective way to reduce friction communicating are likely stretching the truth a bit. Camille Fournier’s take is clearly a warning that it could be easy to get wrong, so if I do try it out at some point, I’ll be treading lightly.
Whether or not I personally write something down, working to understand yourself is important. When was getting ready to be a Dad, I learned about HALT . It is an acronym to remind you that your behavior is influenced from Hungry, Angry, Lonely and Tired. Hangry was another one that helped define why you might have a short fuse. This was a valuable tool for two first time parents experiencing an extreme lack of sleep and caring for a new life. When someone might be snippy, we could ask, “are you hangry?” and we recognized there were some factors at play that might be causing some unintended negative behavior. When my wife would bring it up, I would often stop and take a mental inventory. By knowing and naming I might be hungry, tired, or had a headache, I could easily accept the criticism and change my behavior. My theory is that a User Manual or README can help in the naming of negative behaviors so the team can help hold each other accountable for making changes.