Documentation is a big part of diversity and inclusion
I was able to attend MongoDB World this year, thanks to a generous scholarship from Mongo. I was very impressed by all of the new features released, and the variety of talks scheduled throughout the day. One of the panels, Effective Strategies for Supporting Gender Diversity in Industry, left me thinking about something for weeks after. One of the panelists, Esha Maharishi, a senior software engineer at Mongo, talked a bit about how documentation is part of creating a welcoming environment.
Esha could not be more right. Tech companies are realizing the need to hire diverse teams to build better products and get more perspectives to improve workflow and quality. Part of bringing in people from underrepresented groups is bringing in a variety of backgrounds: both cultural and technical.
Writing documentation is not easy. As engineers, we joke about what a drag it is, and about how we don’t always understand our own code. By the time we’re done writing code, it feels like it should be obvious how it works and how decisions were made in the codebase, because we’ve put a lot of thought into it. However, those of us who have looked back at a project a few months later, often find code that was written by an insane person. Our past selves always seem to make the craziest decisions and take the weirdest shortcuts — if we can’t decipher our own madness a few months later, how can we expect anyone else to?
Starting a new job is generally terrifying. The first several weeks are usually spent nervously asking coworkers how things work, what the expected workflow is, what conventions must be followed, what permissions you need, and who is responsible for which parts of each project. All the while, there’s a lot of pressure to prove that the company made a great decision in hiring you. This can be even more terrifying for people from underrepresented groups, who have historically felt underrated by their peers, and fear that asking too many questions will annoy those around them and make them seem unqualified. Generally, when you start a new job, you want to hit the ground running. You don’t want to spend time trying to decipher the right person and timing to ask questions, all while holding your breath that the answer wasn’t actually obvious the whole time.
Make new people feel welcome by giving them as much information as possible up front. Assume that everyone reading your documentation is at their first day on the job.
- Explain the role of every person on the project and how to get in touch with them.
- How does the project relate to the goals of the company?
- Why were these tools chosen and who chose them?
- What are the naming conventions?
- What are the linting rules, if any?
- What server does it live on and who has the credentials for it?
- What does the deploy cycle look like?
- What coding patterns did the developers try to adhere to?
- How do you set up the project? If there are multiple ways to set it up, who uses what way?
- Write as much as possible about the general structure of the codebase and try to be detailed in how that came to be.
This seems like so much information, and it is. And it should be in every single codebase. You never know where a new person is going to start. While everyone else in the company may have all of that information from other projects, someone starting fresh doesn’t have any of it. This documentation should not be hard to find — every new person should know where to find it on their first day. Does it take a lot of effort to keep that much documentation up-to-date? Of course. But it’s worth it.
Your company wants to hire a diverse workforce, and wants to be known as a place where the best want to go to work. The best employees want to do good work right away, and will feel immediately more comfortable and confident if they can just get started. Comprehensive documentation should allow anyone to jump in and start contributing. There will always be more questions asked, but as soon as they are, they should be added to the documentation for the next person. Give all of your new employees the tools to succeed, and they will!
