An increasingly common practice among software engineers and those engineering-adjacent is to write a “readme.” Inspired by the instructional documents bundled with software and prefacing codebases, these documents typically outline what it’s like to work with someone, and what their preferences and expectations are.

Distributed teams don’t have the same touchpoints throughout the week as those who work together in the same physical office, so we need to be a bit more intentional about how we build relationships. Part of that is showing up as a complete person, and creating the sort of environment where others can do the same.

And so, this is my own guide for crafting a personal readme. For transparency’s sake, this is just about the same version I intend to publish at my place of employ (without references to internal policies, procedures, and the like).

Outlining Your Readme

You’ll find that I go into a lot of detail in my readme, delving into a couple aspects of my personal life that influence my perspective (and therefore my work). And I want to be very clear: you don’t have to do the same.

I choose to voluntarily disclose my various identities and my disabilities. I’m in a place in my life, my career, and my personal situation where I feel that’s best for me. This wasn’t a decision I made lightly, and it took literal years of reflection. You are under no obligation to disclose your disabilities, identities, or any facet of your life you do not feel comfortable sharing, full stop. You may choose to do so, but that is your choice and your choice alone—it’s not a requirement.

What Should Go in Your Readme

The idea is to provide a primer on who you are professionally, and what it’s like to work with you. Consider including:

  • A bit about yourself and your background
  • Your role on the team
  • How you prefer to communicate
  • Anything your colleagues should know about working with you

What Shouldn’t Go in Your Readme

While it probably goes without saying, you should avoid anything that:

  • You feel uncomfortable sharing
  • Is privileged information, or you do not otherwise have consent to share
  • Violates the policies of your specific organization (many have things to say about political activities and the like)
  • Would be otherwise inappropriate for the workplace