Blog Home
Your Team Needs A User Manual... On You
Darryn King
Darryn King
Freelance Writer
1.12.2022
min read

Do you README?

Several years ago, an employee at the tech start-up Ultranauts found himself trying, and failing, to get through to a colleague. "I can't figure out how to work with some of the people on my team," he said in passing one day. "Wouldn't it be great if humans had a quick-start guide?"

That half-joking remark led to the creation and implementation of what the Ultranauts team calls the Biodex, an organized collection of "quick-start guides" on every member of the team, accessible to every member of the team, written by the team members themselves.

In the Biodex, Ultranauts employees list their personal working styles and preferences, their strengths and their weaknesses. In short, they provide the answers to the sort of questions that arise when humans have to find a way to work with other humans.

Why hasn't so-and-so gotten back to me? When is so-and-so most likely to want to discuss this? Would they prefer to receive critical feedback via Zoom call, phone call, or some other way?

With the Biodex, the answers are only a couple of clicks away.

For a time, these sorts of documents were written by managers for the benefit of their new reports. (This one, by Roy Rapoport, then of Netflix, was an oft cited example of the form.) Today it's common — and increasingly seen as common sense — for every member of a company to write one up.

The documents go by different names at different companies; at Almanac, we know them as READMEs. But, essentially, the idea is the same: The Definitive Guide to Working With Me — By Me.

"In a typical work environment, many of us might have worried about how a communication was going to be received," Rajesh Anandan, CEO of Ultranauts, told me recently. "We might have agonized over the wording of a message we were about to send, second-guessed approaching someone who didn’t look like they wanted to talk, become anxious while waiting for a teammate to respond to a request, or gotten triggered by feedback from a well-meaning colleague.

"The Biodex is our way of reducing communication friction and increasing collaboration."

Because we all work differently.

I encountered the idea of the README for the first time very recently, when I joined the Almanac team and was tasked with writing my own.

I'll admit I cringed a little.

As a journalist, a teller of other people's stories, it sounded like self-indulgent navel-gazing — the long-winded relative of the online dating bio.

And the term README, rendered in all caps, struck me as both desperate and menacingly robotic. It's borrowed, of course, from software technology, where such a document would typically contain configuration and operating instructions, and troubleshooting advice for pesky bugs. They aren't exactly known for being page-turners.

It turns out I'm not the only one who had an adverse initial reaction to the concept. "Honestly, I was initially a tad hesitant to share a document entirely about my preferences and quirks," Camin McCluskey, Co-Founder and CTO of Telescope, told me recently, admitting that it seemed a bit "pompous" to dump the results of one's epic Knausgårdian self-excavation onto a hapless colleague.

I eventually realized that the README is the opposite of self-centered. Inspired by the simple and obvious fact that different people have different ways of working, READMEs signal a team's willingness to work with each other's different ways of working.

"It is a touch point for teams to understand how best to work together," said McCluskey. "Most people want to be considerate and accommodating."

That touch point is even more important for distributed teams, who can easily lapse into misunderstandings or feel disconnected — anathema for effective collaboration. "Small sources of friction and stress can build up over time when everyone's remote," said Anandan. (Ultranauts has been fully remote since its launch in 2013.) "Ineffective communication can result in teams feeling disconnected, losing trust and becoming unproductive." The Biodex — or a handy compendium of READMEs — is "an easy way of reducing communication friction and increasing collaboration."

McCluskey agrees: "As with so many things in a remote-work environment, the tacit must be made explicit, including and especially interpersonal relationship knowledge."

Because we need to see our colleagues as real people.

No one said the README had to be strictly business.

For starters, a README is incredibly handy when it comes to a question as simple and fundamental as, How does one pronounce so-and-so's name? (GitLab CEO Sid Sijbrandij's comprehensive README, for instance, includes a useful pronunciation guide.)

READMEs have also become a place for team members to get to know one another, to reveal more of their authentic selves and who they are outside of work.

This might include everything from your life ambitions to your favorite book from the last year, your professional background to the sports team you support, or any other go-to conversation starters. (Darren Murph, GitLab's Head of Remote, mentions his Guinness World Record — I mean, wouldn't you?)

There is, perhaps, even an opportunity for a bit of vulnerability — that element which Brené Brown has called "the birthplace of belonging and creativity."

A well-organized collection of thoughtfully written READMEs can help you find a teammate that shares your interest in crochet or deep house music (or both). It's something to bring up in your next Slack conversation or pre-meeting small talk on Zoom.

In other words, in a remote-working world, the README can serve the function of the mythical water cooler of our bygone office-bound era.

Even without the discovery of common interests, these are valuable glimpses of one another's individuality. Which is great in itself, while also priming us for the kind of team bonding — and the associated neurobiological processes — that's so essential to effective collaboration.

It's time to get personal.

Reader, I wrote a README.

I boasted about my ability to spot an errant punctuation mark at fifty yards, while also expressing my "bring it on" attitude to ideas and constructive criticism. I freely admitted that a clogged calendar was creative kryptonite (which compelled me to think about ways I could protect my schedule). I openly confessed to being confused by much tech/business jargon (and that the initials "ICP" make me think of the Insane Clown Posse).

I also happened to mention being the proud parent of a lop-eared rabbit creatively named Buns (see above).

It was, I realized, a useful exercise in focused self-reflection.

"For me personally, the most surprising thing about a personal README is not the benefit derived from sharing it with others, but rather the benefits of focusing hard on one's own personal preferences for work," said McCluskey. "Taking the time to do that illuminated areas that I myself could change about my schedule, work environment and professional relationships that have made me happier and more productive."

In the past few weeks, my README has made a huge difference to my work with my Almanac teammates. My workday rhythms have been respected, colleagues have felt free to come to me with suggestions, there's been a notable reduction in tech-world jargon all-round, and everyone regularly checks in about Buns.

Of course, like the nature of one's being, one's README isn't set in stone. It is a living, working document that you can update as your own working style and preferences shift and evolve. That's as it should be.

You Might Also Like

Join a live demo of Almanac
Learn how Almanac works in under 20 minutes.
Save my seat