Increasingly, companies across the tech industry are realizing that they can no longer rely on traditional sources of candidates for their hiring needs. That’s great news! Opening doors to a more diverse workforce has meaningful competitive advantages. In a tight job market, it can be essential for filling open roles. Expanding opportunities for women, people of color, and self-taught individuals is a worthy goal with a huge upside.
But gains won’t come without dealing with some new challenges. The tech industry has a longstanding reputation for being impenetrable to outsiders, as illustrated by the number of characters and situations in popular media that play up “incomprehensible” jargon and arcane problems. Obviously, there’s a lot of exaggeration in those stereotypes, but there’s also an element of truth. The tech industry can be obscure when you’re on the outside looking in.
If you’ve worked in the technology industry for any length of time, you can probably point to at least one experience where bad documentation (or no documentation!) turned you away from a product and led you to seek a new solution. It doesn’t take much imagination to realize that such experiences are going to be more common for people coming from non-traditional backgrounds.
If you’re committed to increasing inclusion and representation in the tech industry, you need to think about whether you’re creating a welcoming first impression for users from all backgrounds. For most API users, your documentation is going to be where you make your first impression. Making room for diversity in your documentation means creating a work environment where all people can be comfortable. On top of that, SaaS companies have an opportunity to make a significant contribution by creating a developer experience that invites developers from all backgrounds through compelling and inclusive documentation.
What does it mean to create documentation that is inclusive and welcoming? In this article, we’ll discuss exactly how you can make your docs contribute to a more inclusive tech industry.
Documentation Practices That Matter for Inclusion
Improving the inclusivity of your developer experience doesn’t mean rebuilding from scratch. At the most basic level, good developer experience is inclusive developer experience. So if you’ve been focusing on good best practices, you’re on the right track.
Here are a few areas to target in your documentation that specifically aid users from nontraditional backgrounds:
Consistency: (which can be done through implementing style guides for your API program)
Almost every grocery store you go into, regardless of where you are, will be laid out in basically the same way. The companies running those stores know that consumers are more likely to come back if they can quickly find what they need on a first visit. A grocery store is a pretty inclusive business – they have a vested interest in satisfying as many different types of customers as possible, and they do it by focusing on practical, predictable organization and consistent product offerings.
Approach your documentation the same way. Industry standards like OpenAPI help new users orient themselves quickly to a familiar pattern. Clear navigation options and a consistent API style improve discoverability for both features and documentation. Following a writing style guide like the Microsoft Style Guide ensures your tone and style are consistent and appropriate to the task. Automating and embedding API documentation with a tool like Stoplight’s Elements lowers the barrier to entry for new users by providing a clear framework for your docs.
Approachable Tone and Plain Language
Convoluted jargon is probably the single most effective signal gatekeepers have for telling users they’re not truly welcome. So get rid of it!
The Microsoft Style Guide, which we mentioned above, makes voice the very first section. The key idea is to write in simple terms that everyone can understand. When subjects are complex, make your writing even simpler. Users may be coming to your product with relatively little formal education, as self-taught developers, as non-native English speakers, or simply with little time to get the job done. Make their lives easier by providing documentation that is easy to understand. In turn, they will have a faster on-ramp to using your API product and will appreciate that your product speaks to them.
Use-Case Driven Organization
At Stoplight, we’re advocates for Design-First approaches to APIs. In particular, we advocate for designing around stakeholder use cases. That approach makes documentation more navigable, too. Many people who move into web development from nontraditional backgrounds have a lot of experience in other fields and are motivated by the potential to use technology to solve practical problems.
Your API documentation needs to meet users where they are and speak to their needs, which means it needs to be more than a list of endpoints and methods. Thinking about your potential users as a diverse group with diverse goals can help you organize your documentation in a way that inspires creativity and reflects the real world.
Practical Guides
Use cases, interactive docs, and hands-on guides to implementation are great ways to make your documentation more engaging and inclusive. Think creatively here! There’s no reason that every sample app needs to use the same data or address the same tired use cases. Highlight use cases from diverse companies and developers, and provide sample apps and technical guides based on a range of real-world scenarios.
It’s important to note that this isn’t an invitation to patronize your users. Developers coming from nontraditional backgrounds bring an enormous wealth of knowledge and experience from other spheres. Inclusion is not about lowering expectations, but about broadening them. When you think about how your documentation can better reflect the growing diversity of the tech community, the goal should be to remove unnecessary barriers and emphasize real-world applications.
Gates Should Welcome Users, Not Keep Them Out
The term “gatekeeping” comes up often in discussions of inclusion and diversity. In practice, many of us have learned a habit of speaking in a certain way to reflect ‘in-group’ knowledge. In an ideal world, we know better and don’t actively want to keep others out. But in the course of learning all of the necessary skills to be a software developer or technical writer, it’s entirely possible that you’ve built up the habits without knowing it.
If you don’t want to be an unintentional gatekeeper, there are a few simple things to focus on in your documentation.
- Be alert to discriminatory language. Again, Microsoft’s Style Guide has a succinct section on bias-free communication that has been widely adopted.
- Avoid in-group language. Jargon, acronyms, and inside jokes can push people away. If you think someone from outside the tech industry might not understand a term, either define it, or use a different word. Replace in-jokes with more universal references, and be especially sensitive to any jokes that might offend users.
- Use clear variable names and function names in code samples. Avoid terms that require special familiarity to understand.
- Be careful of assuming too much prior knowledge! You don’t need to include a detailed discussion of every concept in every document, but where you can’t explain in context, link to another source with a definition or in-depth discussion.
Increasing inclusion means removing barriers that don’t serve a purpose. When you do that, more people will be inclined to test out your product and will have greater success with it. That can translate into more long-term users, deeper integrations, and naturally positive brand affinity as devs share their successful experiences with your API.
Striving for diversity in the tech industry requires a multi-faceted approach. When we commit to improving the developer experience for devs from nontraditional backgrounds, we work towards greater inclusion. We’re creating a better industry for everyone and nurturing an environment where innovation thrives. It’s a long journey, but it starts with just a few simple steps.
