Personal README Experiment

by Rachel Davies

You’ve all heard the old adage:

There’s no ‘I’ in ‘Team’.

Teamwork would be much easier if we were working with clones! But we are all unique so we have to find a way to figure out how to work with other people who don’t think like us. Remember, we travelled different paths to reach the current point in our career and picked up different skills along the way. Often these differences are what help us to come up with creative solutions.

It is so easy to accidentally annoy someone by expecting them to be exactly like us. When we learn how each person likes to work, we can remove some of the friction that tend to come up. There seems to be no shortcut apart from spending time getting to know a person and this is more of a challenge when we work remotely. How nice it would be to have a guide on how to work with a person.

At Tes we drew some inspiration from Manager READMEs (see this article for examples) and decided to try an experiment by creating personal READMEs that might be useful to our fellow engineers.

The Experiment

To create a place where we can share personal READMEs across Engineering at Tes. Our aim is to improve communication by providing a means to learn about each other.

During our recent monthly Hack Days, we implemented a simple solution. Individual engineer READMEs are markdown files that we can edit on Github. We use Docasaurus to generate a static site from these.

To look up a profile, engineers can browse the internal site or use a handy Slack bot command that returns a profile link for a given slack user.

To give everyone a headstart, we scraped a list of engineers details to provide profiles for everyone. We also came up with template with basic contact information plus some questions to prompt your own content.

What’s in a README?

Engineers can put whatever they like in their personal README. A README template is provided as a guide. Here’s a cut-down version of the template we came up with:

Screenshot of our template

When building up your README, it’s worth taking time to reflect on how you like to work and what is useful for other people to know about you.

What’s next?

Personal READMEs provide a way for each of us to share something about how we like to work. By encouraging our engineers at Tes to share something about themselves, we hope teams will find it easier to talk about personal preferences.

Right now, I’m delighted to see engineers at Tes are publishing their README profiles and I’ve already learned some new things about my colleagues.