Why did I bother with a README?

5 min readNov 25, 2022
Photo by Roman Kraft on Unsplash

I had seen README documents before, but I didn’t realise their full potential until I recently wrote one for myself. Using READMEs became a popular trend with GitHub profiles, where people could showcase their skills and achievements. However, the README pages shared internally within a company serve a slightly different purpose; they paint a complete picture of someone at work and possibly outside of work. In addition to a personal/profession background, you would also see useful information about someone’s communication style or what is like working with them. In this article I will explain how I approached it, and what I learned as part of this exercise:

The audience

As an engineering manager, the main audience for my README would be my team and people working directly with me. After moving to remote work, I have had far fewer interactions with my team, mostly very transactional: we start a Zoom call on a specific topic at an agreed time, we get to an agreement, and we end the call. Most of the simple and frequent interactions have now disappeared and the team no longer observe many cues useful for building a big picture about someone at work. It’s no longer very obvious to them, for example, when I show up at work or leave, how much time I spend at my desk vs. in meetings, how much I join random conversations, what I typically talk about, etc.

The assumptions

In the absence of clear communication, assumptions are made. These assumptions often have negative effect on our work as a team. Here is an example: if one of my team members sees my calendar (shared with everyone in the company by default) they would assume I am very busy and if they have a question or concern they should wait until our next 1:1. This is definitely not what I want as my first priority is unblocking my team. I had no idea a few people in my team had made this assumption. The only reason I know that now is because some people in my team mentioned that after reading my README page. I am hoping that you are now convinced that there are some benefits in this exercies, let’s take a look at the message I have tried to convey this way.

The message

In my README, I have mainly touched on the following topics:

1. My personal life; background, family situation, sport and hobbies:

I would like to be seen as a person first, in my unique situation, with my unique interests and challenges.

2. My communication style; how I can be contacted, and how I prioritised incoming messages

This should help people to know how they should reach out to me if they need my attention.

  • I practice zero-inbox and I have a system to filter different types of notifications, responding to them in a specific order. This means in order to get my attention, you don’t necessarily need to leave a comment on the Jira ticket and also ping me on Slack. If this is not urgent, a simple comment will get you a response with the next 1–2 days.
  • When it comes to Slack, I first prioritise responding to Slack messages from my team (direct messages from managers and direct reports, mentions in the main team channels), then mentions in other channels, then responses to active threads, then other DMs and channels and n-way chats. This will encourage conversations to come through channels (me not becoming a bottleneck) and will discourage unnecessary n-way conversations (which mostly could be done in a channel instead). With this order communicated, I can commit to regularly responding to high priority messages, without committing to a life spent on Slack busy-work.

3. My working hours

I have a busy life outside of work, with two kids, each in a different stage of life. Therefore it is very important for me to use all the flexibility I get in working hours. At the same time, I need to set expectations about when I am typically available. More importantly, I need to make it very clear that even though I may work during evening hours / weekends, this is only my choice and it should not be seen as norm. No one also needs to respond to messages / notifications they receive from me outside normal business hours.

4. My promise, as a manager, to my team

This is the most important part of the README. This is where I try to clarify what the team should expect from me and conversely what I expect from them. This is where I get to debunk most of the assumptions that are made in the absence of a shared understanding. I declare my position on topics like 1:1 conversations, goal setting, time management, etc. Here is one about having regular 1:1 conversations:

My promise to you

I have a weekly 1:1 with you. These 1:1 conversations are rarely cancelled from my side.

What I expect from you

You bring topics to our 1:1, but we will also use a shared agenda page, so we don’t forget important issues.

You don’t need to provide a status report unless you want to raise issues or ask for my opinion. I should get that from daily stand-ups, planning sessions, and what you write in your journal. Therefore, I highly recommend developing a work journal that is updated at least every week, not pages of text, but a few bullet points about the significant events and achievements since the last time we talked.

Don’t wait until the next 1:1 to raise an important matter that is bothering you. Ask away in Slack, or send me a calendar invitation for a quick chat. If you can’t find an open slot in my calendar, ping me. I should be able to find the time.

Here is what I had about growth conversations and goals:

My promise to you

I have regular growth conversations with you, trying to help you achieve your career goals. The annual assessment will summarise all the growth conversations we have had so far without any surprises.

I have an interest in your growth beyond your current team. If you have reached the ceiling in your current team, I will work with you to find a better home in Atlassian.

I work with you to define and track goals, but you will never be assessed based on what goals you chose or how you progressed towards them. These goals are here to help you grow in your career. Having them helps you focus and invest in them, and helps me provide the right opportunity through work.

What I expect from you

If you are not happy where you are, or if your work isn’t aligned with your long-term career objective, let me know as soon as possible. Give me a chance to help you before you start looking for an opportunity elsewhere.

5. My management style

Finally, for anyone who cares to understand more about me, I expand on what management style I believe in and share the outcomes of the assessments that I believe paint a better picture. There are a few different types of assessment available, but StandOut and MT DISC fit perfectly with my audience.