How to design technical content with inclusivity in mind

In this talk from DevRelCon New York 2024, Maria Ashby addresses accessibility in technical documentation and why it matters for both users and businesses.

She shares practical tips for balancing simplicity with depth, making sure content reaches both beginners and experienced developers. Emphasizing the value of a layered approach, Maria explains how to create paths that welcome newcomers without losing experts. She also looks at the importance of visuals, context, and hands-on learning to increase comprehension and engagement.

Maria’s message is clear: accessibility isn’t just good practice—it’s smart business that strengthens community connections and drives adoption.

Watch the video

Transcript

Maria: We’re going to talk about one of my favourite topics in developer relations and developer education in general, talking all about lowering the barrier to entry into technical content, technical documentation, and all the good things that make developer relations fund. So my name is Maria, and let’s get started. So first I’m going to ask the question of the day, are you smarter than a fifth grader? And the answer is probably not. And then more about me, developer educator, a hottie, an engineer by trade. And frankly, overall, a good time. And my current vice of the summer is Ralph’s Italian ice cream. Ralph’s is the reason why I’m going to be wearing high wasted swimwear season.

All right, so pop quiz. Can you identify the preposition in this sentence? The cat jumped over the fence. Don’t call it out, just think in your head. Alright, did, how many people guessed over as a preposition? Alright, a little bit more than half. So this is pretty accurate. So more than half of American adults read below a sixth grade level.

And what this means is more than half of your audience that you’re writing for speaking to making video content for is at that reading comprehension level. And studies have also shown that when people encounter information that they’ve never seen before, their reading comprehension goes down significantly. So think sixth grade or below. Remember that. So with this information, how do we design technical content with inclusivity in mind? So my agenda, I’m going to be talking to you about the challenges, the solutions, some strategies to get us there, and a quick inclusion.

So there’s a huge gap in developer education. A lot of the people who write technical documentation and produce technical content already are pretty proficient in the domain that they’re talking about. So often times they have a one size fits all approach to building their documentation and creating content. A lot of times they only have developers, product managers, other technical writers in mind when they create that content. But that ends up leaving a lot of people out of the equation. Additionally, if you can imagine yourself, think about yourself earlier in your developer journey, when you guys are going to other docs, a lot of times it’s almost overload, it’s overloaded with jargon, these deep, advanced technical concepts without actually explaining what is going on. So this happens all over the place in our industry, and I believe that through the next few slides we can talk about alleviating that gap.

And just for some context, I went through a bunch of different open source documentation and I started reading through it. I synthesised the content and ran it through Gemini and chat to BT to get an average of what the reading levels were. And when I say reading level, I’m more talking about reading comprehension. So it’s not just the content, it’s how it’s structured. And so Prometheus, I’m a Kubernetes grow by trade. So Prometheus is a Kubernetes monitoring solution, and that is at the undergraduate college level when it comes to reading comprehension, which makes sense, I struggled a lot when I was learning it. And then Flux, which is another Kubernetes tool, it’s a continuous delivery tool that’s about the high school, I would say at junior level for reading comprehension. And then Panda is my girl.

She’s at sixth grade level. That’s probably why I’m a pandas advocate.

I wish I was being paid by them, but let’s manifest it. So this actually comes at a great cost. So a lot of times when people talk about accessibility, they’re talking about it, oh, let’s be accessible, let’s let everybody in. Let’s be inclusive. They talk about omas from a benevolent mindset, but there’s a real cost to leaving people out of the equation. So you’re leaving C-suite people out of the equation. So there are lots of times when you’re selling software, when your customer’s c-suite might just want to look at the documentation and see what they’re buying, you’re leaving out compliance. So when a large enterprise wants to purchase your software, if they don’t understand what it does, they’re going to have a hard time making a case to implement it into the system.

Legal and finance. So if you think about a lot of companies are getting acquired IPOs, a lot of financial people from institutions, investors, they’ll be looking at your documentation to see what your product actually does and if it’s a fit for being in their investor portfolio. So these are a lot of people that aren’t developers or are not in that technical mindset that would be reading and observing your documentation and also your documentation, your blogs, your videos are people’s first impression of your software. So if you go and look at the docs or you go and watch videos and you’re confused, I’m probably not going to use it. I think all the time about when I was early in my developer relations journey and going to different open source documentation, I’m like, oh, this sucks, but I’m on the clock so I’m going to stick through it.

So I think about a lot of times when people are interacting with these documentation of like, they’re not on the clock, I would log off on going on YouTube instead. So you’re really competing with other products, other solutions. So you have to really think about this is their first impression. So here’s one of a part of the solution. We have to really focus on clarity. So this means we got to keep it simple. So a lot of times people get lost in the jargon, they get lost and go on these deep, deep rabbit holes. But frankly, you can explain a concept within a paragraph.

If you don’t have a paragraph saying in the beginning of your documentation, your videos or blog of saying, this is what this software does, you’ve already lost everybody. And second, as Beyonce says, you are the visuals, baby. Visuals are so important. So many people really struggle with being able to visualise what they just read. So by implementing using diagrams more interactive videos samples, you can really help increase their reading comprehension.

Additionally, you have to have some context. You have to actually know who your audience is. So I talked about the wide variety of people who would be interacting with your documentation or your content. So you have to find this balance of how do I make it open and welcoming to absolute beginners, while at the same time being able to engage experts because docs aren’t just for people getting started. Docs are for people who want to find out what’s new in the latest release. They want to find out how they can continue to implement your product more deeply into their system. So you might be also dealing with experts as well, so people who might want to contribute to your project. So you have to find that balance for creating your content.

And last, you got to be concise. Just spit it out. I mean, I feel like sometimes when I read some articles, it’s just going on and on and on when all I could think of is this could have just been 300 words and a gif and call it a day. So you have to think about the perspective of your audience. Like I said before, a lot of people are reading this in their free time or using it for research purposes so they’re not on the clock. So you have to be able to get your ideas across pretty quickly and effectively so you can make sure that your audience is able to want to advocate for your product, want to try out your product, want to implement it. You don’t want them to spend 20 minutes on the documentation when they can just spend five minutes on the documentation and then spend 15 minutes actually playing with your product.

So here is the strategy. One way that we can be successful is to have a multilayered and module approach. So I’m breaking my own rule by using a high school SAT word, but I feel like it’s very important. So by multilayered you should have multiple learning paths. So a lot of really successful open source projects have a quick start guide. They have a whole section explaining why you’re here, what the product does, the context that it exists, the context of why it was built, while also at the same time having a section for you to skip ahead and for experts and advanced people to just get started with more in depth use cases for them to learn about more complicated features. So you have to have a multilayered approach to your content creation. And this applies to videos and articles as well.

So if your company has a learn section, your learn section shouldn’t just be 1 0 1, you should be able to level it.

And one company that does this really well. So this is Kubernetes, they do it well. And another place that does it well is AWS. So if you’ve ever been to an AWS reinvent or AWS summit, if you notice all of their workshops and sessions all have levels to it, and they all explicitly say who the workshop is for or who the session is for, they will have AWS for business leaders or AWS for marketing leaders. And they clearly put in the prerequisites and level set the content that you’ll be presented. So you can take that lesson from AWS, and I think part of the reason why they’ve been so successful is that they’ve been able to master the art of level setting when talking to people and apply that to your own content and your own projects. And second, you want to have a modular approach.

So you want to have a logical approach to the instructions that you give. I know this sounds pretty basic, but if you think about it, so all of us here at some point probably was learning how to read, but if you try to teach a three-year-old how to read, it’s pretty hard to explain to them why the cat sound, the A and the cat sound is that way. It’s, it’s pretty hard for us to conceptualise being in that position. So you have to make sure your approach is logical that A plus B equals C. A lot of times when people are writing documentation, they almost skip steps because they don’t even think of them as steps. So one great example is sometimes you’ll go to a project and they’ll say, okay, just run your website locally. But what does that mean? Nobody actually explains what that means.

So you’ll have people lost on step one. So you need to have some sort of logical way of explaining and then about that prerequisites piece. So when I tell my audience, run your website locally, and I don’t give them any sources on how to actually do that, they’re not going to want to stay engaged with my product or my tool. So I have to be able to give them all the resources. And if I can’t do that internally, I have to point them to external resources that they can go to.

Second, you want hands-on learning. So in my experience working with K through 12 students, I’ve learned a lot about learning. And learning is not just collecting information, it’s being able to receive information and to act on it. So in your technical content, you should provide space for hands-on learning. I think it’s very apt that one of our sponsors today is instruct. So they definitely embody that as a company. So when you learn something, it’s great to be able to practise it immediately. And you also want to provide your audience, your customers, your users with an opportunity and a safe space to fail while they learn.

So a lot of times your ideal user is maybe an enterprise software engineer that’s learning how to use this software for the first time. So let me use the example of Kubernetes. At the end of the day, they want to learn how to deploy their databases to Kubernetes.

Sure, but they might not have the opportunity to have a sandbox environment because all that they’re given is their work environment with very, very highly sensitive data. So they’re kind of lost. So if I were building the documentation, I would provide some sort of sandbox environment, some sort of repo, some sort of code sample so I can show my audience how to use it safely. So when they inevitably mess up along the way, that they’re able to do that safely without actually causing risk to their system. So this is another great way as we talk about sales and layoffs and other sessions to really get that enterprise client to want to work with you. Another thing is we really want to experiment with different formats. I know there’s going to be a lot of sessions talking about video and social media, but it’s very true.

We are in this really diverse community with so many different backgrounds and people have such a funny way of learning things. For example, in the hallway, I learned how to tie a strappy heel with a TikTok, but for some people they might not be able to learn that that way. So you want to really expand and be creative when it comes to how you present information. A great example is the children’s guide to Kubernetes. That’s actually how I really understood Kubernetes for the first time, is seeing those little animals and boats showing me how containers work. But it doesn’t have to be that extreme. There’s other ways to be creative and really learn how to put yourself in the position of your audience. And then lastly, you want to really work on establishing a feedback loop through your community.

So I’ve always believed that community goes both ways.

You’re in a bi-directional relationship with the people that you’re serving, the people that you want to use your product. So by doing this, you want to meet your developers where they are. Our keynote speaker talked about this a lot, and I a hundred percent agree. You can’t expect people to come with you to their problems. I think the average person, when they’re struggling with something, the first instinct is to not ask the senior engineer who built the thing how to fix it. So you want to create a space for your developers to come meet you and say, Hey, these docs are kind of confusing. Can you help me fix this? Maybe they’re out of date.

There’s three different ways of installing something. I’m very confused. What’s the best way to do this? So you want to either insert yourself into the developer community that you’re trying to serve or you want to build it from scratch.

And I know that sounds daunting, but even just a group chat can save a life, honestly, or just even making yourself available, have a Calendly link with office hours to just help people instal. And you’d be so surprised on how that improves your user metrics. And speaking of metrics, you want to measure everything. So in this climate where money is very expensive and people are always thinking about budgets and funding, you want to actually measure the work that you’re doing. So I think a lot of times in developer relations, we have these abstract ideas of, okay, if I do B, I’m going to change, get a million dollars in revenue. But you have to actually work backwards. So when I’m improving my content, I’m improving my documentation, I have to have very clear metrics of why am I doing this? So I should say, okay, right now it takes the average user an hour to instal.

So my goal is to reduce installation time by 30%. So I’m going to work backwards. Who do I need to talk to, figure out how to make installation easier? I mean, the first thing I would do is phone a friend, a random person, I don’t know the man on the subway with a computer. Hey, can you instal my product and time you? Can you tell me what steps are the most difficult? And then you can work backwards and say, is this a documentation problem? Is this engineering problem?

Is this a product problem? And then from there, you can really start to make an impact on your project or your product as a whole. So you really want to measure everything and measure user acquisition. Are people talking about this product more now that it’s easier to use? Do I have external advocates now? So these are the things that you should keep in mind as you do your work.

So in conclusion, I really want to reiterate, the accessibility is not just altruistic, it’s just good business practise. So I was actually talking to my partner on the train about this. So I know there’s a controversy about all the iPad kids everywhere, babies with iPads, but there’s a reason for it because Steve Jobs was saying, you should just be able to pick up an iPad. You should just be able to pick up your computer and open it. It should be an easy user experience. And I think we should start to really apply those concepts to the software that we’re building. One thing I’ve just really noticed is that a lot of people in certain communities almost have a chip on their shoulder for how difficult it is to use their software. And I think we really need to reverse that.

Building software that’s difficult to use does not make you more intelligent or a better engineer.

In fact, it’s the opposite. You should be able to explain what you’re doing to everyone, and that’s how you get true adoption. So it’s not just about doing the right thing, it’s good for your business as a whole. That’s why Apple’s a trillion dollar company and Samsung and the Galaxy phones are struggling because it’s hard to use. And last, you want to start small and iterate. So as developer relations teams and developer advocates, we tend not to have a bunch of funding. We tend to have all these super grandiose ideas. I’m going to start a community advocate team from scratch.

I’m going to go to a million conferences, and we have all these big ideas, but we don’t really have steps to do it. So starting small could just be having office hours for two hours a week and saying, Hey, ask me a bunch of questions.

I’m really curious. Tell me about your least favourite thing about the docs. We can change the font. You got to start small and you have to iterate often and get everybody involved. It’s not just a developer relations problem. If you’re building all this really cool software and nobody knows how to use it problem, that’s products problem, that’s sales problem, that’s everybody’s problem. So you want to make sure as you build and as you iterate, you get more and more people into the conversation. So we’ve learned that we got to think like we’re teaching fifth grade, we got to think simpler, and we got to really focus on making sure our content that we create, that we take so much time to do is able to touch everybody and everybody is able to understand it.

So thank you so much for having me today. Yeah, any questions? Oh, sorry. Last thing. Open source isn’t just being free. It must be accessible to all.

MC: Thank you, Maria. That was fantastic. Please raise your hand for questions and shy. Our friendly q and a runner will come to you with a mic.

Audience member 1: Hi, I’m, I’ve run into this problem definitely where some developers find it difficult, they come to a meeting with questions. Hey, you have an example in TypeScript. How does this work in JavaScript? Right? Where do you draw the line? You’ve mentioned, for example, showcasing how to run things on locally. I always show yarn instal commands as well, how to instal the package. But where do you draw the lines and make sure that you want to be concise, but you cannot have too much of the basics there.

How do you think about that?

Maria: Right. So I think the best way to do it is to really be very particular about your prerequisites. So if you have all your examples in TypeScript, say that in the beginning of your docs, this documentation is written TypeScript. If you have the resources, maybe even have a link to having your documentation in JavaScript or even say, we’re looking for people who are experts in JavaScript who can remake the docs, put it into a separate GitHub repo. But you want to be concise in the packaging. So you can just say at the beginning, this is for TypeScript experts. If you need other help, I’ll send you to another place. Does that answer your question?

Yeah. All right, great.

Audience member 2: Quick question. What are your great presentation, by the way? What are your thoughts on internationalisation and your strategy for increasing users beyond your native language?

Maria: That’s an excellent question. I think it’s a really big problem in this industry. I think in the same way that we had a movement away from everybody needs to be a computer science grad and really opening the doors to bootcamp grads and people from non-traditional backgrounds. I think the next stage in the movement is focusing on putting these large open source projects in different languages. And the way to do that is to really go to these communities. So I know there’s a lot of movements for developers in Latin America, developers in India, and reach out to those developers and say, I see that there’s a problem of our docs only being in English. How can I help you translate this into Spanish? What resources do you need?

Do you need funding? Do you need mentorship? Do you need engineering resources? How can I help you do this? How can we work together? So I think it’s about seeing the problem, seeing what resources you have available, and then collaborating with those groups.

Audience member 3: Hello. So this is kind of fun because I’m following up on Yi’s question, but because Yare was one of the first people on my show, teach Gentech where I was learning tech two years ago, I had no idea what I was doing. The first stream was literally C-S-S-H-T-M-L, and JavaScript. And what’s the difference? I couldn’t tell you when we started that stream. That being said, everything you’re saying makes sense, and I’m so grateful for it because I didn’t know those things. But how do we ask for those things when we need it for people getting into a new parts of the industry, new languages, new? How do we request it?

Because I know for myself, I’ve been shut down many, many times. And so as somebody that has a show about trying to learn tech, I literally have stopped asking so many questions, like, I don’t want to feel dumb. And people talk down to me a lot. So how would you suggest to us getting around that?

Maria: Well, thank you, Jen, for your candour, your vulnerability, and your question. So first thing I want to say to that, we’re all lifelong learners. So everybody is at a different stage in their journey. So anybody, and I mean, anybody who makes you feel bad for beginning, they’re the wrong person. So I believe it’s our job as developer advocates to be that warm person, to be able to say, there’s no such thing as a stupid question because you’re intelligent for even recognising that you don’t know something and asking that question. And then on the flip side of being that person in that position, I was listening to this great podcast of How do you make your First million or something? And he said something really great. Being small, weak and defenceless is a superpower because people don’t see you as competition.

So you can ask as many questions as you want.

So if the first person says, I don’t want to talk to you’re dumb, go to the next person, go to the VP of engineering and say like, Hey, I love your product. Can you teach me how to use it? And eventually you’re going to find somebody that says, yes, but you fail. When you stop asking questions. You got to keep pushing. And I know that’s putting a lot on the learner, but until we get to a point in this industry where we can comfortably say that all are welcome and we really mean it, that’s unfortunately the price we’re going to have to pay as learners. Any other questions?

MC: Awesome. Well, thank you so much, Maria. Give her another huge round of applause for that amazing talk.