Communication
Writing Inclusively about Technology Topics
Edit
#inclusivity
#diversity-inclusion
#writing
#documentation
#communication
#user-experience-ux
Summarized using AI

Writing Inclusively about Technology Topics

Thursday Bram • November 28, 2017 • New Orleans, LA

The video "Writing Inclusively about Technology Topics" presented by Thursday Bram at RubyConf 2017 focuses on the significance of inclusive writing within the technology sector. The speaker, an experienced writer and editor of the Responsible Communications Style Guide, begins by defining inclusive writing as communication that avoids assumptions about identity (gender, sexuality, etc.) and respects the humanity of the audience. She emphasizes engaging the audience by providing context and diverse perspectives, illustrating the evolving standards of inclusivity through concepts like the Bechdel Test, which, while merely a starting point, highlights the need for deeper inclusivity in writing.

Key points discussed include:

- Inclusive Writing Definition: Thursday provides her personal definition as writing that respects the humanity of individuals, avoids assumptions, and allows audience connection.

- Evolving Standards: The evolving nature of inclusive writing, as seen through the Bechdel Test and its limitations.

- Style Guides: Style guides as essential tools that help writers maintain consistency and respect in their communication. She encourages creating project-specific style guides to avoid biases and stereotypes.

- Interview Techniques: Importance of asking, rather than assuming, individual's preferred terminology, especially regarding pronouns, and the significance of preparation in interviews to promote inclusivity.

- Editing for Inclusivity: Emphasizes having a structured editorial process that checks for biases, stereotypes, and ensures accurate representation. Techniques like diversity metrics and unconscious bias training are highlighted as valuable tools.

- Practical Exercises: Several activities engage the audience in recognizing how to make job listings more welcoming and discuss which details to include when writing biographies.

Throughout the talk, Thursday provides practical insights and engaging quizzes to reinforce the message about accessibility and openness in technical writing. She underscores that inclusivity is a skill developed over time through practice and continual learning.

Concluding the talk, she advocates for the establishment of style guides within teams to streamline writing processes and ensure coherence in documentation. The main takeaway is that inclusive writing not only enhances communication but significantly contributes to fostering a more welcoming and effective technology community.

Writing Inclusively about Technology Topics
Thursday Bram • November 28, 2017 • New Orleans, LA

Writing Inclusively about Technology Topics by Thursday Bram

Whether you're writing documentation, a talk for a technical conference, or a blog post on your work, identity can impact how your audience perceives and uses both written material and code repositories. If you want your work to be accessible to a wide audience, you need to write about it in an inclusive way. This talk will give you hands-on examples and resources to do just that!

RubyConf 2017

00:00:10.510 Hello! How are all of you doing? Awesome!
00:00:18.040 All right, I think we can get started now because my timer has already started.
00:00:23.779 So, we're going now. My name is Thursday Bram, and I've been writing about technology for over a decade now.
00:00:29.720 God, I feel old! I've written blog posts, case studies, documentation, ebooks, and very, very many social media posts.
00:00:35.660 I'm the editor of the Responsible Communications Style Guide, which covers how to write about identity in the context of technology.
00:00:42.440 This is my baby; this is what I spent the last year on. One of our editors isn't in the audience as well, but we're here to talk about inclusive writing.
00:00:53.570 I find it really useful to start from a high-level perspective to talk about what inclusive writing is. Oh, and this is the talk where you get handouts, possibly even homework!
00:01:06.350 So, talking about inclusive writing, I find that it's really useful to start from a shared definition. This is going to be interactive; I know that's scary, but I will try to only call on people who want to be called on. What do all of you think of as inclusive writing? What's your definition? Anyone have one they want to share?
00:01:27.170 [silence] Anyone? Bueller? Bueller?... Yeah.
00:02:01.690 So inclusive writing is avoiding assumptions about gender, sexuality, and details like that.
00:02:07.580 It’s also writing so that you connect with your audience rather than alienating them, which hopefully is the goal in the first place.
00:02:24.550 Okay, yeah.
00:02:40.270 Contextualizing information is important so that it's accessible and easy to understand for people, with links to other resources and documentation.
00:02:52.720 Those are all really good definitions. My personal definition of inclusive writing is writing that respects the humanity of the people it describes.
00:03:07.300 That kind of speaks to all of those aspects: you want to respect them by not making assumptions, you want to ensure they can engage, and provide them with all the information they need.
00:03:14.050 Another characteristic of inclusive writing is that it can include a diversity of perspectives. Any characteristic that accurately describes people is a question of respect.
00:03:27.330 We're really looking for characteristics of inclusive writing that make people feel welcome and do not inaccurately describe them.
00:03:43.330 Inclusive writing does have moving goal posts, though. Consider the Bechdel Test, first proposed in 1985. The Bechdel Test asks if a movie meets three criteria: first, does it have at least two women characters; second, do they talk to each other; and third, is that conversation about something besides a man?
00:04:00.460 We are talking about an absolute bare minimum here. The Bechdel Test doesn't ask for actors of color, queer roles, characters from beyond the gender binary, or even for those women to talk to each other for a set amount of time. Goodfellas passes the Bechdel Test because two women talk about shopping for a moment. It is a very low bar, but in 1985, it was a higher one than it is now.
00:04:25.660 Our goals have to keep moving forward. Inclusive writing, no matter the medium or the intent, continuously evolves. If the Bechdel Test used to be our goal, we need to think about what we can do to move past that, especially outside of screenwriting. For instance, being able to bring in more terminology, more information, and more context is a good start.
00:05:02.050 So a lot of those questions are about style. Whether you use a standard approach to any of your writing, you're creating a sense of style for the work you're doing. Talking about inclusive writing has to be a question of normalcy and style.
00:05:38.200 For example, a normal movie these days includes both picture and sound, even though a century ago, movies and talkies were distinct types of media. These standards aren’t always written down; there’s no law that says a movie has to have sound, but today, going silent is very risky. It’s part of the style that we consider normal for movies.
00:06:06.370 Similarly, there’s no rule that says you have to be a white dude to be on the cover of Wired magazine. Often, that’s exactly who winds up there. That's because magazine covers generally feature people and media that focus on groups with privilege unless an editor makes a special effort to change their sense of normal or style.
00:06:38.110 Style, in this context, specifically means making a decision; you're deciding what’s going to be standard or normal in your particular project. You might style an article by choosing to indent certain blocks of text or choosing to stylize someone’s name in a particular way.
00:07:03.760 We can make our writing more inclusive by creating new normals that come from conscious decisions about our language choices.
00:07:15.680 With this in mind, let’s discuss style guides, which are kind of my favorite thing. The idea of a style guide is a way to remember all of our style decisions. Once you’ve made a conscious decision about your style, you need a way to stick with it without having to make the same decision repeatedly.
00:07:30.800 This is like trying to remember the difference between words like 'affect' and 'effect' when you are in the middle of writing something. No writer, programmer, or anyone doing this sort of work does it without some sort of external resource. We at least run spellcheck and check a style guide for additional information. Hopefully, if spellcheck doesn’t handle it, we have a couple more resources.
00:08:15.290 Style guides are tools to make writing easier. They grew out of journalism; my first love was the AP Stylebook, which I learned in college. There are many others ranging from technical topics to talking about religion.
00:08:25.960 I actually make my own style guides for nearly every project I do. I even made a style guide for the style guide we worked on. It’s a bit meta, but it’s really helpful! I have a document with all the project-specific information, like each participant’s name spelled correctly, sometimes with notes on how to pronounce it. Since I am a white girl from the Midwest, I sometimes need some help with pronunciation.
00:09:06.410 I also usually put all the latest technical jargon and the resources anyone else will need if I suddenly can’t work on this project and need to hand it off.
00:09:26.420 So, do style guides that originate from journalism mean that they’re useful for technical communities?
00:09:32.300 Absolutely! A style guide is a way to bring together the voice of the project and avoid making significant mistakes that you have to correct later. For programmers, there are many recommendations on how to write code, including how many spaces, how many tabs, or any of those details.
00:09:50.080 But a style guide is the easiest way to get everyone on the same page. Just like pep 8 in the Python community is effectively a style guide for code, you can have different style guides that focus on technical information.
00:10:08.270 For instance, designers use style guides to avoid color choices that people with color blindness might struggle with. So, you may also wind up with more than one style guide on your desk for a project; in fact, you often should have more than one style guide.
00:10:29.960 Because it’s a question of graceful defecation. If you need a project-specific style guide, that’s great, but you might also need an industry-specific style guide, or even a more general style guide like the Chicago Manual of Style, which covers everything.
00:10:51.930 These are practical tools for improving inclusivity. Because no matter how good our intentions are, we’re all human. So if we have documentation or tools to help us with inclusivity, it becomes easier.
00:11:10.460 Think about how hard it was to switch from typing one space after a period to two; you’ll only make the switch if you understand why it’s worth the effort. You’ll need some editing help in the meantime. Learning to use, say, the singular 'they' if you’re not used to it can feel like a similar level of effort.
00:11:38.100 So, you all have mini style guides now, and since we’ve been discussing them, we’re going to actually use them! For instance, if we want to make sure that we’re using somebody’s pronouns correctly, we could look up in our style guides for pronouns.
00:12:23.570 Does somebody want to read the entry for us? Yeah! So, it can be that simple. You just ask people. But we need reminders to ask sometimes, and that’s where the style guide comes in.
00:12:39.210 Okay, so you might have seen this a little bit before. I have a journalism degree, and I had this professor who would give surprise quizzes on AP style just to check who brought their style guide to class. In honor of that dedication to the importance of style guides, I’m going to give you all a pop quiz! Audience participation makes it more fun!
00:13:06.930 All the answers are in your style guide! Number one: When referring to the Chief Technical Officer of a corporation for the second time, how should you abbreviate their title? Heidi, you can't answer this because you helped write the book! Sorry; see ya. CTO, capitalized!
00:13:32.150 Alright. Number two: The Disney movie Pocahontas is based on a true story about a (A) blank woman born around 1596 (B). So why is it B and not C? Right, because B is more specific and accurate.
00:13:46.830 And especially when talking about someone's identity, we want to be as specific as possible, because being general makes it much harder to be accurate.
00:14:06.200 Alright, number three: How do you spell the name of the Jewish festival of lights, which traditionally falls in December? I heard somebody say that it was a trick question! Over here it is indeed a trick question! A is a good answer, but because different communities of Jews transliterate the word differently, they will have specific preferences.
00:14:27.000 For instance, in my family, I spell it 'A,' but my aunt, who’s ultra-Orthodox, spells it 'B.' This makes searching and using Gmail for what she wants for presents much harder.
00:14:49.740 So, that's one of those cases where you absolutely have to ask.
00:15:01.500 A/B could absolutely work, but it depends on your project and what choice makes sense in the moment.
00:15:09.710 One of the things that in tech we wind up doing a lot regarding writing and inclusive media is interviewing people quite a bit, whether it’s for writing a quick bio for their contributions to a project, making sure that when you’re talking about them in a presentation, you get everything correct, or even deciding whether to pursue a certain candidate for a new job.
00:15:27.200 With interviewing, it’s a really useful way to think about inclusivity because we have to ask people what they want, such as their pronouns. People’s pronouns change, so not only do we need to ask them what they want today, but we should probably be aware of what they're using next week.
00:15:46.210 When conducting interviews, we get a chance to sit down and ask some questions. Even if you’re looking for just a quick summary, there are a few strategies that you can use to make inclusive interviewing much easier. The three that I focus on are: preparing for every interview.
00:16:06.400 Given that you’re probably not going to be paying someone for the time they spend answering questions, the etiquette of unpaid labor requires that you be as prepared as possible, which also makes the whole process easier.
00:16:27.430 Writing out questions ahead of time lets you make sure that you’re using time effectively, and that you don’t miss anything you need. If you're planning your interview, you can Google some stuff ahead of time too, so you don’t have to make the whole interview about having your subject walk you through all the basics of whatever they’re working on.
00:16:46.240 This way, you can get to the interesting stuff and perhaps even win a Pulitzer Prize or something, because you have interesting content to work with.
00:17:06.910 Secondly, you want to ask rather than assume. Personally, at the beginning of every interview, I ask key biographical information just to confirm what I might have found online.
00:17:22.738 I usually start by asking what someone's name is and exactly how they prefer to spell and pronounce it, even if I think I know; the same goes for pronouns.
00:17:43.280 I ask specifically about their pronouns, their job title, because job titles can be very different from what you find on their LinkedIn if they haven’t updated it.
00:17:57.600 All those little details can be really awkward if you have to correct them later. You can just ask directly in an interview where you don’t have to admit that we are all human and fallible.
00:18:17.590 Thirdly, you want to avoid asking questions that you don’t need to ask. For a lot of projects you work on, you might not need as much information about your subject’s identity. For instance, if you are writing a profile of an astronaut who happens to be a woman, you don’t necessarily need to ask how she fits in time for her kids.
00:18:31.080 You wouldn’t ask that question of an astronaut who happens to be a man, so checking yourself and saying, 'no, this isn't relevant to the profile of someone related to their work,' is important.
00:18:48.570 Alright, so we have a little follow-up activity in your booklet. We have a couple of personas, and we’re just going to talk about what details we think are important to include in a bio of any of these people.
00:18:58.350 So, we’ll focus on the first persona because I’m already at 20 minutes, but tell me what details make sense for a bio rather than details that don’t make sense.
00:19:06.000 If you're writing about Luna Lafayette, what do you want to make sure makes it into her profile? Any thoughts?
00:19:52.000 It absolutely does matter where the profile is going to be! For this purpose, let’s say Lafayette has just joined your company, and you want to introduce her to the rest of the team. What’s the first thing your team needs to know about Luna?
00:20:05.250 That she is the smartest person in the whole world? Yeah, that's probably a good thing to lead with. Are there any details here that don’t matter to a profile?
00:20:18.700 Like giving a nickname absolutely personalizes somebody and makes them more accessible. It makes them more familiar right off the bat. So absolutely ask her what she would like us to know. Okay, what about her wearing glasses? Does that matter?
00:20:49.740 No, that's medical information; it’s not really helpful.
00:20:57.500 So, while I can’t help myself, we’re going to do another little pop quiz! So, what is Doctor Princess's job title? Physician! Yes, correct!
00:21:13.420 What about number two: how do you spell Uriel’s last name? It depends on where they’re from, right? So this person is Asian, but he has anglicized his name and has been using his family name as his last name.
00:21:31.500 Nice catch! Alright, number three: what are Luna's pronouns? She/Her. And then for the bonus round, where are these three characters from?
00:21:50.942 Because I steal my material whenever I can, I’m very lazy!
00:22:03.400 Yeah, Luna is Moon Girl from Marvel; she is the best, and she has her own dinosaur. Uriel is from a sports anime called Yuri. Ah, nice! And then Doctor Princess is from Adventure Time, and she is neither a doctor nor a princess but is still a physician.
00:22:30.560 This poses the greatest trick question for style guides because many people think that the title 'doctor' equates automatically with the profession of being a doctor.
00:22:43.500 So, let's talk about editing for inclusivity real fast. Depending on how you write, you may ignore details like spelling to get some words on the page and go back to fix them later.
00:22:59.000 Because good spelling doesn’t make good writing, it’s a good strategy, and one that I use all the time. However, if you focus on getting words on paper, you need an editorial process to make sure you go back and get things right.
00:23:16.070 For example, running through spellcheck, and this is a short version of my personal checklist.
00:23:32.145 Check your style guide or guides, double-check for stereotypes, microaggressions, and unconscious biases. If you're still developing an understanding of these concepts, Facebook has free unconscious bias training on their website that is pretty fast to go through, all videos.
00:23:52.190 I also keep diversity metrics in my work, tracking who I’m writing about and their demographics to make sure that I’m not just writing about one group of people on a regular basis.
00:24:09.900 Lastly, confirm name spellings, dates, and other facts, all the stuff a fact-checker would do if journalism wasn’t, you know, dying and fact-checkers couldn’t get work.
00:24:28.880 And because I like activities, we have another one! So there’s a job listing in your booklet, and I’m not going to tell you what company this job listing came from. I only made like two changes to it; it was special when I found it.
00:24:39.600 So with this job listing, let’s talk about what we can do to make it more welcoming or friendly, but we can’t change company policies like the number of years of experience required of an applicant.
00:25:01.900 What are some things here that we can change to make this job less intimidating and a little bit more welcoming? Get rid of the term 'ninja.' Yes, ninjas are not what you're necessarily looking for in a full-stack programmer; their martial arts capabilities probably don't impact their coding that much.
00:25:21.670 Also, using the word ‘sexy’ to describe technology isn’t appropriate either. I don’t have any sort of romantic attachment to any piece of technology I work with, and that’s an odd way to describe it.
00:25:39.700 Anything else to remove? Yes! Remove the term 'Death March.' I would like to say in another discussion on this job listing, somebody mentioned that they didn’t want to remove it because they wanted to make it clear this company was terrible to work for.
00:26:01.950 That’s fair warning, I guess, but I think that you can communicate how a company is cultured without resorting to using language that is steeped in a lot of meaning. For instance, many people with a Jewish or Native American heritage will probably respond very poorly to that word, as well as many other communities.
00:26:27.990 Yes, language choice matters a lot in these types of job listings. And those weren’t the pieces I changed, but if anybody has any guesses about that company, please don’t share them on camera or anything; I would prefer not to get sued!
00:26:49.830 So, getting into the actual writing part of inclusive writing: communication is a skill and not necessarily something we instinctively know how to do. We should think of it as a long-term learning process.
00:27:11.950 We have to keep learning new pieces of the communication puzzle and finding ways to put them together in new ways. Personally, I learn a lot by reading widely, but that’s not always enough.
00:27:33.204 Sometimes you have to talk to actual humans. There are lots of details you won't pick up otherwise! I still maintain that Home Depot is where tools come from because I learned the term 'Depot' when I was five years old, not from a human.
00:27:55.180 We have to try out new words to incorporate them into our vocabulary; we need to practice using them to truly learn them.
00:28:13.000 Inclusivity skills are exactly the same. I know that classes and homework can be exciting, even when you’re in school, but being able to improve our work always holds value.
00:28:35.010 Some of the terms we’re discussing didn’t exist a decade ago! It’s important to approach all of this understanding that we need to continue learning.
00:28:57.440 Most style guides come out every year for a reason, and practice is the only way to improve your writing, whether you’re working on inclusion, spelling, or any other writing skill.
00:29:35.210 You don’t have to write the Great American Novel, but you do need to look for opportunities to practice. If your company asks you to write a blog post, that could be a great opportunity.
00:29:50.800 Hopefully, your company will give you some editorial support. If your company doesn’t provide that support, reach out to me on Twitter later; I have some resources.
00:30:06.080 We don’t have enough time to engage in an actual inclusivity writing activity, which is something I really like to do. One recommendation for practice is to find someone you need to talk to, ask their pronouns, name, and details, and write up a little bio about them.
00:30:22.190 They may even want to use that bio later because writing your own bio can be a tough task.
00:30:47.350 So, this is, of course, a fast talk. We only have 40 minutes to go through a large amount of information. After this talk, I hope you practice and continue to learn, but my ideal outcome is that you go back to your communities and your companies and start creating your own style guides!
00:31:27.190 That's the dream! I know it’s only my dream; not everyone finds style guides fun. But even if you aren’t sold on the appeal of compiling lists of correctly spelled and formatted words, that's fine. I encourage you to keep practicing as much as possible.
00:31:54.690 Concern talking to your team about committing to a shared style guide, even if it’s one you’re not creating in-house, to make editing easier.
00:32:11.509 Your colleagues might find this information particularly persuasive! They no longer have to argue about what gets capitalized in the company name if you can agree on camel case or some other format, and it can be written down to avoid disputes.
00:32:29.450 Style guides and other editorial workflows can speed up projects, reduce errors, and lessen stress, especially while trying to complete documentation or marketing content under deadlines.
00:32:49.197 Your team’s sustainability will increase too. Even without a dedicated editor or technical writer, your team will be better equipped to produce written materials that appear cohesive.
00:33:06.720 Instead of a haphazard collection of work from everyone, you can also enable everyone on your team to participate in editing, sharing the workload. Every programmer should be able to conduct a code review at any time.
00:33:22.730 Also, if you establish a standard approach, you can build tools that make that standard approach even simpler to follow. One of our style guide goals is to develop a linter that tells us what to do, as it will be a resource that simplifies writing.
00:33:38.180 You can automate parts of the editing process; of course, you still need a human involved somewhere. You can tweak and hack and customize a style guide or an editorial process to your heart's content.
00:34:04.730 And I know that, while working with programmers, it’s half the fun to be able to tweak those processes.
00:34:26.760 So, you want to customize your arguments for your team if you want to bring this kind of resource in, just like you customize your style guide by adding the correct spelling of your organization’s name.
00:34:49.450 Does anyone have questions? The question is: how do you approach someone who uses terms that we would discourage, such as 'sexy'? There are a couple of approaches I take depending on who the person is.
00:35:22.290 If they’re above me in some hierarchy, it’s a lot different than if they’re a peer. With peers, it can be as simple as saying, 'Hey, this isn't going to be effective. Let's just change it.' You don’t have to get into a whole argument.
00:35:43.920 That’s where the style guide comes in handy—many people find it easy to comply with if you just hand them a style guide and say, 'Do it how the book says.' With someone a little higher up, it is more challenging; you often need to take a softer approach.
00:36:08.710 But with inclusivity, there are numbers and figures to support our argument. For instance, Forester conducted extensive studies and found that companies hiring inclusively raise their bottom line by 20%, increasing revenue by that same percentage.
00:36:44.500 So, if you’re editing a job listing for inclusivity, you can tell your boss that doing things right can significantly raise revenues.
00:37:04.430 It’s a harder sell in open-source contexts, because revenue may not be the primary goal. But if you belong to a community with a code of conduct, you can reference that.
00:37:20.290 If someone comes back to one of these edits or suggestions, saying they didn’t mean to communicate in a specific way, this is where I start talking about the evolution of communication.
00:37:35.890 If it’s someone I like, we can discuss how language and communication change. If we were using words from the Victorian era, we wouldn’t be able to program today, and communication would be drastically different.
00:37:51.580 Technical training is a part of inclusivity too. Training is available on many of these topics.
00:38:07.660 Any other questions? Especially surrounding using 'they/them' as a singular pronoun. How do you avoid alienating people who learned it was only used in the plural in school?
00:38:30.190 This can be complex. If someone prefers 'they,' it’s less a preference than a matter of identity. I will always default to ensuring I am writing about them accurately.
00:38:52.920 Even if the audience isn’t completely comfortable. That said, there is much you can do in terms of educating people on an individual level.
00:39:14.260 It's usually not the place of an article to include exhaustive explanations of topics like pronouns. However, you can engage with people by showing that the goal of this effort is to describe people better and more accurately in the way they wish to be described.
00:39:36.660 It extends beyond just pronouns. For instance, as someone who is Jewish in the U.S., there are a lot of terms that can describe Jewish identity, and while some of them are respectful, others are hurtful.
00:39:54.830 Explanations can sometimes be effective with those who are reluctant to endorse inclusive language. For those still resistant, you may not find an argument that persuades them.
00:40:13.440 In such cases, it is more about doing what is right for those you are communicating with than ensuring that everyone feels perfectly comfortable. Thank you for your time!
TB
Thursday Bram
1 talk
Explore all talks recorded at RubyConf 2017
+83