Diversity and contributor experience: Building documentation with empathy

Aizhamal Nurmamat kyzy, Riona MacNamara from Google

May 14th, 2019, 4:10 PM (duration: 20 minute)

Location: Emporium Logan Square Arcade Bar

Good engineering documentation not only drives adoption and supports developers; it's also critical to supporting community contributors. Clear documentation of a project's processes, such as contributor guides and codes of conduct, are especially valued by under-represented groups and are vital to building inclusive communities. But in practice, 93% of OSS devs complain about the lack of good, reliable documentation, making it the #1 problem they face when working with open source software as GitHub's 2017 open source survey revealed. In this talk we will explore the journey for a person from being interested in a project, to deciding that they want to become a contributor, and how the lack of empathetic documentation can turn them away. This hinders a project’s ability to create a diverse pipeline of potential contributors. We also propose a set of principles, and practices for projects to adopt in order to drive inclusive documentation that will help to create vibrant communities. We will wrap by sharing examples of projects that have had deliberate strategies to build empathetic documentation, and what are some lessons to be learned from them.