Importance of Inclusivity in Technical Content
The speaker, Maria, emphasizes the need to make technical content more inclusive and accessible, particularly in developer relations and education, to lower the barriers to entry for various users.
Audience Reading Levels
Many users read at a sixth-grade level or below, and comprehension drops when encountering unfamiliar content. This necessitates designing documentation and content for a broader audience, not just experts.
Challenges in Developer Education
Often, technical content is tailored for experts, leaving out beginners and non-technical stakeholders. Overloading content with jargon and complex concepts can alienate users.
Real-World Impact
Accessibility issues in technical content can result in missed opportunities, lost sales, and compliance challenges for enterprises.
Focus on Clarity and Conciseness
Maria highlights the importance of explaining concepts clearly and avoiding unnecessary complexity. Providing concise, understandable content encourages engagement.
Multi-Layered and Modular Content Creation
Effective documentation should cater to different skill levels, offering beginner-friendly guides alongside advanced materials. Examples include Kubernetes and AWS, which use leveled approaches to content.
Hands-On Learning and Safe Practice Environments Encouraging hands-on practice with sandbox environments allows users to safely experiment and learn without risk, enhancing comprehension and confidence.
Diverse Presentation Formats
Technical content should be presented creatively using visuals, diagrams, interactive examples, and varied formats to accommodate different learning preferences.
Community Feedback and Interaction
Building community-driven feedback loops ensures continuous improvement of documentation. Creating spaces for open dialogue with users helps refine content and addresses gaps.
Metrics and Continuous Improvement
Measuring user engagement and content effectiveness helps in refining the documentation process, boosting user satisfaction, and aligning with business goals.
(00:00) we're going to talk about one of my favorite topics in developer relations and developer education in general um talking all about lowering the barrier to entry into uh technical content um technical documentation and all the good things that make uh developer relations fun 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 um and then more about me uh developer educator um a hottie um an engineer by trade and frankly overall a
(00:45) 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-waisted swimwear All Season all right so pop quids can you identify the preposition in this sentence the cat jumped over the fence don't call it out just think in your head all right did how many people uh guessed over as a preposition all right a little bit more than half so this is pretty accurate so more than half of American adults read below a fifth gr uh sixth grade level and uh
(01:30) what this means is more than half of your audience um that you're writing for speaking to making video content for is at that reading comprehension level and um 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
(02:09) there and a quick conclusion 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 suff pretty proficient in the domain that they're talking about so often times um they have a one siiz fits-all approach to building their um documentation and creating content a lot of times they only have developers product managers um technical other technical writers in mind when they create um that content but that ends up leaving a lot of people out of the
(02:49) equation additionally um if you can imagine yourself um think about yourself earlier in your developer Journey when you guys are going to other docs a lot of times it's almost information over overload um it's overloaded with jargon um these deep uh Advanced technical Concepts without actually explaining um 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 um alleviating that Gap and just for some context um I went through a bunch of different open-
(03:24) Source um documentation and I started reading through it um I U synthesized the content and kind of ran it through Gemini and chat TBT to get an average of What the reading levels were um 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 um so Prometheus um I'm a kubernetes girl by trade so Prometheus is a kubernetes monitoring solution and that is at the undergraduate um college level when it comes to reading comprehension which makes sense because
(03:56) I struggled a lot when I was learning it um and then which is another kubernetes tool it's a continuous delivery tool um that's about the high school I would say junior level for reading comprehension and then panda is my girl she's uh at uh sixth grade level um that's probably why I'm a panda's 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 when people talk about accessibility they're talking about it oh let's be accessible let's
(04:28) let everybody in let's be inclusive they talk about it almost from a benevolent mindset but there's a real cost to leaving people out of the equation so you're leaving seite people out of the equation so there are lots of times when you're selling software when your customers's uh seite might just want to look at the documentation and see what they're buying you're leaving out um compliance so when a large Enterprise wants to you know purchase your software if they don't understand what it does they're going to have a hard time making
(04:59) a case to implement it into the system uh uh legal and finance so if you think about a lot of companies are getting acquired IPOs a lot of financial people from institutions um investors they will 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 so your documentation your blogs your videos are your are people's first
(05:34) 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 um 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 um people are interacting with these documentations like they're not on the clock I would log off on going on YouTube instead so you you're really
(06:04) competing with um other products um other Solutions so you have to really think about this is their their first impression so here's one of the 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 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 in the beginning of your documentation your videos or blog of saying this is what this software does
(06:43) you've already lost everybody and second as Beyonce says you are the visuals baby uh you always visuals are so important so many people um really struggle with being able to visualize what they just read so by implementing using um diagrams um more interactive videos samples you can really help um 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
(07:21) have to find this balance of how do I you know make it open and welcoming to absolute beginners Well 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 you know find out what what's new in the latest release they want to find out how they can um continue to implement your your product more deeply into their system so you might be also dealing with um experts as well so people who might want to contribute to your project so you have
(07:54) to find that balance um for creating your content and last you got to be concise just spit it out I mean I feel like sometimes when I read um some articles it's just going on and on and on when all I could think of is this could have just been you know 300 words and a gif and call it a day um 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 you know be able to
(08:26) 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 could just spend five minutes on the documentation and then spend 15 minutes actually playing with your your product so here is the strategy one way that we can be successful is to have a multi-layered and module approach so I'm breaking my own rule by using a high
(08:58) school SAT Word um but I feel like it's very important so by multi-layered you should have multiple um learning paths so a lot of really successful open- Source uh projects have a quick start guide they have a whole section explaining why you're here what the product does the context that it 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 um experts and advanced people to just get started with um more in-depth use cases for them to learn about um more
(09:37) complicated um features so you have to have a multi-layered approach to your create your content creation and this applies to videos and articles as well so if you have if your company has a learn section your learn section shouldn't just be 101 you should be able to level it and one company that does this really well um so this is kubernetes they do it well and another place that does it well is um AWS so if you've ever been to an AWS reinvent or AWS Summit um if you notice all of their workshops and sessions all have levels
(10:12) to it and they all um explicitly say who the workshop is for or who the session is for they will have you know AWS for Business Leaders or um AWS for um marketing leaders and they clearly put in the prerequisites and level set the content that you will be presented so you can take that um 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 of level setting when talking to people and apply that to your own content in your own projects and second you want to have a
(10:51) modular approach so you want to have a logical approach to the instructions that you give I know this sounds um pretty basic but if you think about it so all of us here um at some point probably um was learning how to read but if you try to teach um you know a three-year-old how to read it's pretty hard to explain to them like why you know the the cat sound the A and the cat sound is is that way it's it's it's pretty hard for us to conceptualize being in that position so you have to make sure your approach is
(11:25) 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 um sometimes you'll go to a a um 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 um way of explaining things and then about that prerequisites piece so when I tell my audience run your website locally and I don't
(12:02) 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 um 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
(12:39) provide space for Hands-On learning um I think it's very apt that one of our sponsors today is an instruct so they definitely um embody that as a company so when you learn something it's great to be able to practice 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 you'll 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
(13:14) of kubernetes they want at the end of the day they want to learn how to you know deploy their databases to kubernetes sure um but they might not have the opportunity to have a Sandbox environment because all that they're given is you know their their work environment with um very very highly sensitive um data so they're kind of lost so if if I were you know building the documentation I would provide some sort of sandbox environment some sort of repo some sort of code sample so I can show how my audience how to use it
(13:48) safely so when they inevitably mess up along the way that they're able to do that safely without you know actually um causing risk to their system so this is another great way as we talk about you know sales and layoffs in other sessions to really get that Enterprise client to want to work with you um another thing is to you really want to experiment with different formats um 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
(14:21) many different backgrounds and people have such a funny way of learning things um for example in the hallway I learned how to tie a strappy heel with a Tik Tok but for some people they might not be able to learn that that way so um you want to really expand and be creative when it comes to how you present information um a great example is um the kubernetes uh a children's guide to kubernetes um that's actually how I really understood kubernetes for the first time is seeing those little animals and boats showing me how
(14:56) containers work um but it doesn't have to be you know that um extreme there's 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 um you want to really work on establishing a feedback feedback loop through your community so I've always believed that Community goes both ways um you're in a biral 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
(15:30) are so our keynote speaker talked about this a lot and I 100% agree you can't expect people to come with you to their problems so I think the average person when they're struggling with something the first instinct is to not um ask the you know senior engineer who built the thing um how to fix it so you want to create a space for your developers to come meet you and say hey like this doc these docks are kind of confusing can you um help me fix this maybe they're out of date there's like three different ways of installing something I'm very
(16:04) 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 um have a cly link um with office hours to just help people install and you'd be so surprised on how that improves your um your user metrics and speaking of metrics you want to measure everything so in this climate where you know money is very expensive
(16:40) 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 um you know change get a you know aill 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 what why am I doing this so I should say okay right now it takes the average user an hour to install so my goal is to reduce
(17:20) installation Time by 30% so I'm going to work backwards what who do I need to talk to to figure out how to make inst easier I mean the first thing I would do is you know phone a friend a random person I don't know the the man on the subway with a computer hey can you install my my product and T can I time you can you tell me what parts are what steps are the most difficult and then you can work backwards and say is this a documentation problem is this an engineering problem is this a product problem and then from there you can
(17:52) really start to make an impact on your your project or your your product as a whole so you really want to measure everything and measure you know uh user acquisition are people talking about this product more now that it's easier to use do I have um external Advocates now so these are the things that you should keep in mind um as you do your work so in conclusion I really want to reiterate that accessibility is not just altruistic it's just good business practice so I was actually talking to my partner on the train about this so I
(18:30) know there's like a controversy about all the iPad kids everywhere you know babies with iPads but there's a reason for it because you know Steve Jobs was saying like 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 like a chip on their shoulder for how difficult it is
(19:01) to use their software and I think we really need to reverse that having 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 like that's why Apple's a trillion dollar company and you know Samsung and the Galaxy phones are are struggling because it's hard to use and last you want to start small and
(19:36) iterate so as developer relations teams and developer Advocates we tend not to have a bunch of funding we tend to have all these like super grandio ideas you know 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 um 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 um tell me about your least favorite thing about the docs we can
(20:09) change the font you got to start small and you have to iterate often and get everybody involved um it's not just a developer relations problem if you're building all this really cool software and nobody knows how to use it that's engineer's problem that's product's problem that's sales problem that's everybody's problem so you want to make sure as you 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
(20:42) think 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 um everybody is able to understand it so thank you so much for having me today right yeah any questions oh sorry last thing open source isn't just being free it must be accessible to all thank you Maria that was fantastic please raise your hand for questions and Shai our friendly Q&A Runner will come to you with a mic hi I'm y um I've run into this problem
(21:31) definitely um where some developers find it difficult they have come to me with questions hey you have an example in typescript how does this work in JavaScript right where do you draw the line you mentioned for example showcasing how to run things on locally I always show yarn install commands uh as well how to install the package but where do you draw the lines and make sure that you know you want to be concise but you cannot have too much of of the basics there how do you think about that right so I think um the best
(22:05) way to do it is to really be very particular about your prerequisites so if you if you have all your examples in typescript say that in the beginning of your docs this documentation is written typescript um if you have the resources maybe even um have a link to having your documentation in JavaScript or even say we're looking for people who are experts in jav who can um remake the docs put it into a separate GI Hub repo but you want to be concise in the in the packaging so you can just say at the beginning this is
(22:39) for typescript experts if you need other help I'll send you to another place does that does that answer your question all right great all right Jen hey quick question what are your great presentation by the way uh what are your thoughts on uh internationalization and your strategy for increasing users beyond your you know native language that's an excellent question um I think it's a really big problem in this industry um I think in the same way that we had a movement away from you know everybody needed to be a
(23:15) computer science grad and really being opening the doors to um like boot camp grab grads and people from non-traditional backgrounds I think the next stage in the movement is um focusing on putting these large open projects in different languages and the way to do that is to really like go to these communities so I know there's a lot of um movements for um 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
(23:51) translate this into Spanish what resources do you need do you need funding do you need mentorship do you need um 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 hello uh so this is kind of fun because I'm following up on y's question um but because y was one of the first people on my show teach genen Tech where I was learning Tech two years ago like I had no idea what I was doing the first
(24:29) stream was literally CSS HTML 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 and but how do we ask for those things when we need it for people getting into uh 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
(25:03) stopped asking so many questions cuz I'm like I don't want to feel dumb and people talk down to me a lot so how would you suggest us getting around that well thank you Jen for your um Candor your vulnerability and your question so first thing I want to say to that um we're all lifelong Learners so everybody body is at a different stage in their Journey so anybody and I mean anybody who makes you feel bad for beginning they're the they're the wrong person so I believe it's our job as developer Advocates to be that warm
(25:49) person to be able to say there's no such thing as a stupid question because you're intelligent for even recognizing that you don't know something and asking that question and then for on the flip side of being that person in that position um I was listening to this great podcast of like how do you make your first million or something and he said something really great being small weak and defenseless is a superpower exactly because people don't see you as competition so you can ask as many questions as you want so if
(26:20) the first person says I don't want to talk to you you're dumb go to the next person like go to the VP of engineering and say like hey I love your product can you teach me how to use it um 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 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
(26:53) Learners any other [Music] questions awesome awesome well thank you so much Maria give her another huge round of applause for that amazing talk [Music]
