Why Documentation is Essential To Your DEI Initiatives

The last few years have seen a remarkable - and much-needed - increase in attention to diversity, equity, and inclusion (DEI) across the tech industry. It would be hard to find a serious player in SaaS, DevOps, or developer tools that doesn't have some kind of DEI mission statement, and most of the people I work with seem earnest in their desire to make changes for the better.

Change is hard, though. It's harder still when you only talk about problems in the abstract. What's often missing from the conversation about DEI is an actionable roadmap for improvement. I get it - it's hard to know where to start, and it's scary to acknowledge where we're coming up short of our values.

That's why I think better documentation is a powerful step in the right direction. It's often developers' first interaction with your company or your community, and ensuring that you are welcoming all kinds of people is essential if we're going to achieve those DEI goals.

How many of us, at some point in our careers in this industry, have found ourselves held back in some way by developer content that didn't meet our needs? We could talk all day about bad advice on crowd-sourced platforms, but even major companies often fill their developer portals with poorly organized, dense documentation that assumes a lot of prior knowledge. Finding the content you need in a form you can quickly grasp can be a time-consuming challenge, even for experienced developers.

The struggle is even more significant for people coming from non-traditional backgrounds. Much of the diversity in the developer community is not coming from college computer science departments. Self-taught developers and bootcamp grads are more diverse in many ways. They often come in with substantial practical skills, but without much grounding in computer science concepts, network architecture, or the history of technology. They also may not have the same 'insider' knowledge of names, events, and memes that industry veterans take for granted.

Documentation that assumes all developers come with the same background is exclusionary -- and there is a lot of it. If we want an industry where developers from all backgrounds feel welcome and supported, we need developer content that meets people where they are.

I'll be approaching this topic from a few different angles in the coming weeks. By no means is fresh developer content a substitute for the difficult, more complex conversations we need to have about DEI. Problems run deep, and solutions are going to require a lot of hard work. My hope is, though, that by showing one simple path towards improvement, I can help you create progress in your organization.