I am going to share a little story with you. Previously, I worked with teams of developers and product managers throughout my career. We were working on new search functionality using APIs developing new APIs. And every day, I was hearing master-slave about the relationships with the APIs. As an African American woman whose ancestors were enslaved people and were slaveholders, it brought many historical relationships of inferiority and superiority. It was hard to focus on solving the problems for our users.
We had weekly retros with this particular group, and I brought it up. I was in a safe space and with people who made time to share and listen to me, and I said, you know, this bothers me. Immediately a group of white American guys with European ancestors empathized with me. They said, “You know what, I don’t want you to feel that way; you are a part of this team. And if this bothers you, it probably bothers other people as well. We can find other terms to use; we can make sure that this language is more inclusive in the future.” But there was one person, just one who said, we have always done it this way. That’s the way it’s been created. And that’s how we’ve seen it time and time again.
But I also want to share with you today that you have the power to do better. And fortunately for that team and me, we then moved forward and used alternative terms going forward. We used new terms, and we still were able to talk about the relationship with the APIs but do it in a way that the language focused on that relationship and did not bring up a lot of harmful historical language. This can be important for team health –
Establishing a relationship where we are being inclusive, where people belong, and where we are practicing what we believe in terms of equality, diversity, and inclusion. That helps build support, that helps build trust within your teams, and engagement. People feel like they belong, and they want to bring up their ideas, share information and solve problems effectively together for our consumers across the world, people of color, and people of all different types of backgrounds – making sure that they feel that these tools are for them as well, that they can use these products that they are encouraged to use these products. That will increase your customer adoption as well. Emotional things that we think of as not that important with technology help with communication tactics and help with the psychology of people wanting to use your tools and wanting to share that with other people. There is some work from the developer side on this.
Having inclusive APIs
I like to start with a quote about systems of oppression and inequality because the idea is that these systems were designed and can’t be redesigned. You have the power to be intentional; when you see offensive language or historically brings up issues of oppression, there are ways that we can change this and move forward together. A great book by Ebron Kennedy on how to be an anti-racist, and ideas when you understand what racist ideas and policies are, you begin to realize there’s a fundamental contrast to that. And that contrast is not some neutrality. So that ties into acting on what you believe. And not only saying, “Hey, I believe that diversity and inclusion are important.” But actually, how do you practice it as a developer, as a product leader? How do you make sure that you live out your beliefs every day? Let us look at some case studies.
Master-slave – This has come up multiple times in my career in different organizations when we talk about APIs. Harmful language brings up feelings of inferiority and superiority. Some examples of what this looks like in our APIs are connecting slaves, building slaves, slave interfaces, etc. We can use alternatives that are more clear and less harmful, e.g., lead-follow, primary-secondary.
Blacklist-whitelist.
This is a case of representative harm, and some alternatives to that are Access list-Deny lists, open list – closed list.
Representative harm means when a system reinforces the subordination of some groups along the lines of identity, and it ties into stereotypes. So master-slave stereotypes who’s a master, who’s a slave. Stereotypes around blacklist whitelist, who has access and who doesn’t have access.
Developers, makers, and designers need to be aware of what these systems can do in reinforcing stereotypes and preventing access equitably. The more you are aware of that, the more you can step in, and you will see better ways to approach this.
Conclusion: there are better ways to create more equitable systems for our global organizations and global audiences.
Designing inclusive APIs
Let us take an MVP approach. Start with the current state analysis, where there is harmful language, and your APIs, style guides, and docs. If you don’t know, invite someone to come and test it out for you, like other API designers and consumers, to look through some of your languages. Partner with UX designers, and tech writers, to help with some of their research, even your tech writers. They can be your first eyes if the language is harmful. Replace that outdated, harmful language. Creating a list of outdated terminology can be helpful for you, e.g., black lists, black marks, dark patterns, etc. API is a form of communication. APIs connect systems, and systems have roles, but we also connect people who are using the APIs, and people have emotions and people have needs, so we need to ensure that we are addressing that.
Creating inclusive style guides is also something that you can do. Look at the language and your style guides. Make sure you have diverse representations, people of color, genders, and ethnicities, including people with diverse capabilities and accessibility and best practices.
Twilio has a great design system that they use for developers and designers to communicate. They are doing a great job with including accessibility best practices and checklists. They have a web design checklist for inclusivity, and it includes information on diversity as well.
Dev portals are another avenue of communication. This can be a place where you can consciously consider inclusive language, diverse representations, and accessibility best practices. Platts is doing a great job here, using their developer portal to communicate. They’re using illustrations and are using knowledge. It is an easy-to-use way for their business users and their API consumers. They are being intentional by using diverse skin tones and ensuring that you include the global community in this work and this practice. That’s another example for you to use as a reference.
Inclusive Documentation
Ensure that the language is inclusive; you use diverse representations, illustrations, and other characters to represent how the API would work with your end-users. Understand if your APIs and the information you create will be usable by audiences who need those assessable features. You can continue this work by training and strategy and hiring an expert to help you with designing and testing inclusive APIs. That is done by assessing the current state of your community health, tracking problem areas and results, partnering with you, and creating strategies for improvement.
Importance of community engagement for the adoption of APIs
Testing your APIs with diverse designers and consumers is a great way to see what you may overlook and find out more information about where there may be problem areas and your APIs where there may be non-inclusive information. Consider this information as you go forward. Use this feedback from your community to help design more inclusive.
