Bring a More Inclusive Developer Strategy to APIs
If over 80% of the internet is connected via the application programming interfaces (APIs) then it’s at the heart of most developer experience. So devs should be well aware that API design must be intentional and not just about technology. Developer-facing businesses must strive to become more inclusive and equitable because it’s both the right thing to do and it’s good for global business. If we are building and connecting the future, we should not just be making things by and for the white male majority in tech. We should be creating an inclusive developer experience that welcomes everyone to contribute to and use our APIs, documentation, and dev portals.
UX Designer Shanae Chapman’s APIdays London talk offered strategies to increase health, trust, support and engagement for both your API designers and consumers. And, frankly, her tips start with low-hanging fruit that allows you to make a big shift towards inclusive language and community around your API. Because, as Antoinette Carroll has taught us, both the technical and socio-technical systems have been designed to be oppressive and inequitable, and so they can — and should — be redesigned.
In this piece, we highlight not only learnings from Chapman, but we reached out to some of the greater developer relations community and include their tips as well.
An MVP to Inclusion
Chapman recommends taking a lean startup or minimum viable product approach to designing inclusive APIs. Start where there is detrimental language within APIs, style guides and documentation. Make the updates and also take the time to explain why you’re updating this and how others can too.
Remember, this isn’t consequential. Chapman often found herself the only Black person in the room, “suffering in silence” for years, while this “careless language used to describe systems and relationships for the tools being developed, that I was helping design,” actively harmed her. She often found examples of where “APIs reinforce stereotypes, subordination, or withhold diverse information.” And these weren’t just written, but white and Asian developers and project managers on the team were carelessly speaking those words.
Until recently, some of the most harmful language in coding has been found right within APIs and their documentation. The master/slave communication and control system is not only an aggressive term, it inaccurately implies one device has control over the other. Primary/secondary, first/second, primary/replica and main/secondary are clearer language choices that don’t traumatize the dependents of enslaved people.
Developer Faizaan Datoo offered over Twitter offered a simple solution of renaming a branch:
- Make a new, differently named branch from the master branch.
- Push that branch.
- Type one command to delete the master branch.
Add to a necessarily ever-growing list of exclusionary language blacklist/whitelist, which should be changed to deny/allow lists, and change the cybersecurity and AI favorite metaphor blackbox to locked box.
Words Matter, but Who You’re Depicting Does Too
And don’t just stop by meeting that lowest bar of eliminating harmful language. Make sure you are intentionally inclusive throughout, whether it’s providing avatars and emojis of all skin tones to not using “hey guys” at work, in an online chat community or at a professional event.
Chapman offered up examples of paragons of inclusion in the API community — and, not surprisingly, they are the same names that always come up as examples of the best API-first strategies:
- Twilio has an inclusive design guide.
- Twitch has accessibility standards including for UI.
- Plaid has an inclusive developer portal.
You may start with an MVP but, as Chapman says, you need to continue with a growth mindset committed to continuous improvement. This can be as simple as making it a deliberate point of consideration in retrospectives and making sure someone follows up on issues that come up. Everyone is responsible for “talking and practicing inclusion in everyday interactions, the codebase, docs, design [and] systems.” Don’t forget about accessible design too. Of course, having diverse leadership will keep all of that at front of mind.
There’s No Such Thing as Easy
Head of community Wesley Faulkner said that we don’t need to just welcome a diverse developer community, but a more diverse level of skill. “Easy” is a word that’s fine for marketing but it should be eradicated from technical documentation — it’s demotivating, condescending and won’t turn trials into customers.
“To include a diverse level of skill, it’s important to remove words like ‘simple’ and ‘easy’ from documentation. If a new learner has an issue with one of these ‘simple steps,’ they may give up and not continue because it’s only going to get harder, right? Removing that wording will help to not add additional pain and shame that comes with learning something new,” Faulkner said.
Technical community builder Rin Oliver says this bad habit comes from assuming everyone learns the same way. In fact, they say, it’s part of your job as a community builder or technical writer to “emphasize that not everyone learns and absorbs information in the same way. Make your documentation accessible with audio and video walkthroughs if you can.”
Remember to design your docs with learning disabilities like dyslexia, dyspraxia, and dyscalculia in mind. “I shouldn’t need a calculus degree to run your app,” Oliver said. And, if a developer actually needs a particular technical or theoretical skill, then say that upfront, so nobody is wasting their time.
This doesn’t mean that you shouldn’t have and flag beginner contributions. Context is everything. Mark contributions for those that are new to using your product or contributing to your community, but also mark what’s for a more advanced skillset, regardless if they’ve used your particular tech before or not. It helps direct more advanced users to go where they are needed, but doesn’t leave anybody behind.
Inclusion Is a Journey, Not a Destination
All of these tactics are even more important if you are trying to nurture an open source community of mostly unpaid workers. Because open source diversity is typically abysmal, even when compared to the overall tech industry.
There’s always more work we can do because the tech industry as a whole is still causing far more harm than good. When in doubt, hire a diversity, equity and inclusion consultant to help you on your inclusive API design journey. And always strive to build a diverse team and to test APIs with diverse designers, to understand the priorities of those under-served and underrepresented in the API community.
Most crucially, never disregard when a colleague or community member speaks up that they feel harmed by something — no matter how small you perceive it. It’s your job, as a manager, a human being, and especially those in the over-represented majority in the room, to listen and help limit that harm as much as possible.
Also, check out this great interview on accessibility from Pivotal Labs‘ senior designer Raquel Breternitz:
Accessibility as an Essential Part of the Inclusive Developer Experience
