I’ve been meaning to write about individual READMEs and “user manuals” for quite some time and I’m glad that I held off.

It was recently brought back to my attention through Ed Batista’s post: To README or not to README. Ed’s been on a tear of good posts lately and I’d highly recommend checking out his blog.

To quickly recap, the idea of creating a Manager README document seems to trace back to the first of such documents being put together almost 10 years ago, in 2012, by a gentleman named Luc Lavesque. The document’s basic premise is highly benevolent — as a manager, deeply reflect on your own work style and preferences and write them down in a sharable doc. The thesis is that this act of self-disclosure, outlining your communication preferences, how you give feedback, your working hours, etc. will create more explicit expectations for your team and lower the likelihood of misunderstandings.

Several different posts have been written about how publishing these documents can backfire, which Batista summarizes rather succinctly:

• A Manager README is no substitute for a feedback-rich culture — and in the absence of such a culture it may even be counter-productive, signaling to employees that their input on your inevitable blind spots as well as your performance as a manager is unwelcome.
• The use of a README without carefully attending to the power differential between you and your employees can inhibit psychological safety. The mere existence of such a document doesn’t necessarily create a less-safe environment — the impact stems from how it is employed.
• The purpose of any such document is a clearer understanding of work style differences, and that needs to be a two-way street. Expecting employees to conform to your preferences without making an effort to understand and adapt to theirs isn’t management, it’s coercion.

It’s that last critique that I want to focus on a bit more. The first two mostly highlight that the README artifact will only have a positive impact in the right context — as part of the feedback-rich culture, while being mindful of the power dynamics. The second critique starts pointing into a more profound issue which is more fully articulated in the third one: the README artifact only captures one side of the dynamic — “this is who I am, and this is how you can best work with me” — where, in fact, this artifact aims to enable better collaboration. And collaboration requires more than one person…

This suggests, that the structure of the artifact is all wrong. It shouldn’t be about you, or me — it should be about us. What are our different work style preferences? and what collective agreements are we making together about the way we work, so we can collaborate well, despite those differences?

Fortunately, we don’t have to start from scratch. The team at SY Partners created a lightweight construct called “How we roll” (see screenshot above) for capturing these differences and beginning to hash out the mutual agreements for working together. In my opinion, it’s a much better starting point than an individualistic README for making the implicit explicit and starting an honest dialogue that can truly help improve collaboration.