Disambiguation, In-Jokes, and Name Collisions: What You Need to Know When Naming a Python Project

Content notes: codes of conduct, colonization, natural disasters, ageism, racism, interpersonal violence, actual snakes

I gave this talk at North Bay Python. I’ve included the text of the talk below, as well as the video.

Names matter.

Names set expectations: a conference with a location name in its title is probably in that location and a Python module with the word “test” in it will do something to do with testing. If North Bay Python took place south of the Bay, we’d all have some questions for the conference organizers.

Names create first impressions. Just reading the name of a project can immediately tell someone whether they’re going to use or contribute to that project. I’ve seen plenty of offensive library names and I’ve decided not to use those libraries just because of their names. I don’t need to look for a code of conduct or at the quality of the code of a project with an offensive name. I just move on. If you really want examples of those names, talk to me privately because I frankly don’t want to say them in public.

There’s a business case against using software modules with problematic names, if you work in the sort of organization that requires a business case to do the right thing: any core maintainer unable to respond to feedback about a problematic name will be unable to consider security risks that don’t impact them directly.

Names endure. Think about where we are right now. Petaluma. Sonoma County. California. The United States of America. The US got its name during the American Revolution. It was purposely structured to make a bunch of colonies sound like they were all working together and knew what they were doing. California is named for a magical island in a 16th-century Spanish romance novel. So, yeah, we use a name from a bunch of Spanish conquistadors thinking fondly of the love stories they read growing up.

Sonoma and Petaluma both come from Coastal Miwok words made to sound more acceptable to the Europeans who colonized this area. Sonoma’s root word means “Valley of the Moon”. Péta Lúuma was the name of the Miwok town located roughly here prior to the area being controlled by the Spanish, the English, the Spanish again, the Russians, the Mexican Empire, the Mexican Republic, the California Republic, and the United States.

Most dialects of Miwok are now extinct, due to the US’s genocidal policies with some European help. Before 1579, Coast Miwok tribal land included all of Marin County plus southern Sonoma County. By 1817, the only land still directly controlled by the Miwok was the Pacific Coast of the Marin Peninsula, from Point Reyes north to Bodega Bay. In 1920, Miwok and southern Pomo tribes tried to move to the 15 acre Graton Rancheria, held in trust by the federal government, but only 3 of the acres were actually habitable. The US government dissolved that trust in 1958 and ended federal recognition of the tribe until the Graton Rancheria Restoration Act was passed in 2000.

The name “Petaluma” endures.

Humans relate to names in deeply emotional and often unnoticed ways. Let’s go to natural disasters for a potentially less depressing example: researchers at the University of Michigan looked into whether people are likely to donate to hurricane aid causes if they connect with the hurricane’s name. Folks who shared a first initial with the hurricane’s name were significantly more likely to donate. That means that Kelly’s, Kai’s, and Khadija’s were more likely to donate to relief efforts for Hurricane Katrina than Hurricane Mitch.

Correlation isn’t causation, but I will guarantee you that there is someone out there thinking about how much money they could raise by choosing a hurricane naming schema with a distribution of first initials more closely matching the distribution of first initials of all our names.

Names don’t exist in a vacuum. Making sure we understand the context and nuances of potential names is a necessary first step.

Python Naming Schema

Question for the audience: Who here knows what inspired the name of the Python programming language?

Monty Python — that’s right!

Monty Python is a British sketch troupe who have turned 45 episodes made between 1969 and 1973 into a bunch of movies, books, games, a musical, and a few other things.

I’m making sure to describe exactly what Monty Python is, because we can’t assume that everyone using the Python programming language also is culturally fluent in Monty Python. I have heard: “Monty Python? I think my grandparents used to watch that.”

That’s because Monty Python turns 50 next year. We might as well be asking programmers to get references to The Beverly Hillbillies, Petticoat Junction, or Green Acres. That in itself isn’t necessarily a problem, but some jokes age better than others. Monty Python isn’t aging particularly well.

By expecting Python programmers to be familiar with Monty Python’s body of work, we’re sending them to look up sketches with titles that include the N word. I don’t think any of us want to accidentally endorse something like that.

I’m not saying you can’t ever make a Monty Python reference again. I am saying we all have to consider the context of our references before slapping them on projects we want to share with the whole world. I’d ask you to think about it the same way you might think about putting a picture of an actual python in the middle of killing its prey up on your project’s homepage. No matter how cool all of you are with snakes, I am more interested in snake jokes and references than I am in snakes themselves.

Within the Python programming community, we’ve established some standard naming schemas, both formally and informally.

We have PEP 8, the style guide for Python code, which includes naming conventions for variables, method names, and such. It doesn’t include suggestions for how to name projects, though there is a little piece of advice I’d love to have engraved on something shiny: avoid names that include the lowercase letter “l”, uppercase letter “O”, or uppercase letter “I”. I think that these suggestions should be followed for more than just single character variable names. They just make names easier to read and retype.

We also have less formal systems, especially for project names. For instance, many Python conferences and user groups include the city they’re located in their organizational names. Geography is a relatively easy way to disambiguate different local communities from larger overarching communities. We can tell that PyLadies Atlanta and PyLadies Santo Domingo are two separate groups. It gets even easier because there are unique identifiers for different locations in the form of IATA codes. IATA makes sure airport codes are unique, since there are very important differences between Portland, Oregon and Portland, Maine, if only because my cats are in Portland, Oregon and they expect me to fly to the correct city today in order to feed them dinner. IATA’s codes are so convenient that sometimes cities use them as nicknames or identifiers . Not all cities’ IATA codes are exactly intuitive. Chicago airports, you better believe I’m looking at you right now.

And while I will always struggle to remember that tickets to both ORD and MDW will get me to Chicago, the sort of “Py*” prefix used in PyLadies has become an easy-to-remember signal that a module is meant for use with Python. There are a variety ways “Py” has slid into Python project names, beyond just the prefix.

Some projects have chosen words whose letters already include “Py”, like Pyramid. “Pi”, spelled with an I instead of a Y, is pronounced the same way (at least in English), so there are also names that use nonstandard spelling like Project Jupyter. And then there’s the word “Pie”, which sounds like “Py” and is generally delicious. CherryPy, for instance, follows this naming schema.

A lot of projects have developed their own internal naming schema as well and for good reason. When related projects are branded together, users are more likely to realize that they can use all the different pieces you create. BeeWare, for instance, uses a combination of puns — so many puns — bees, and history, to create impressively descriptive names. First off, BeeWare has a subtitle, a full name, if you will. It’s BeeWare: the IDEs of Python. As in, what Julius Caesar was told in Shakespeare’s play of the same name, just before he was assassinated by a bunch of dudes in togas, except they’re referencing interactive development environments, rather than the middle of March..

As it happens, Toga is the name of a BeeWare library which provides wrappers for GUI APIs. Because of course, it is. Just like, of course, the name of BeeWare’s prevalidater is Beefore, with two Es.

If it sounds like I’m saying a lot of names, that’s because we name a lot of things. We name them pretty fast, too — fast enough that there are multiples sets of projects sharing a name. I’m willing to bet that most of us in this room have heard of Django, the Python-based web framework. But there’s also a piece of tablature software for musicians, also named Django.

Name collisions are annoying when you’re debugging a program, but they are a full on pain in the rear when you’re trying to search for help online. How many times have you walked away from a meetup or a conference with a Python module in mind to look up once you get home? You really only have three hopes for success for remembering the name:: the project has a memorable name, your new contact remembers to forward you that link, or you manage to find it through a search engine. You might wind up adding a bunch of keywords to your search terms, adding and removing words until you fight the right incantation to summon whichever library you’re looking for.

And if you’re looking for Python modules to help you with your herpetology research, I don’t even know what to tell you, except that I guess some herpetologists might have made the situation much more complicated by naming a species of python after Monty Python.

Name collisions are our future, by the way. Unique identifiers are hard.

Name Selection

As we’re choosing names for Python projects, we have to keep all of these things in our head. Because that seems like an easy way to manage such a big decision, right? Nah, I’m just joking, that sounds super hard.

I actually just went over all of that stuff with you so that I could go over this checklist:

Check for how this name may be used elsewhere
Talk to actual humans about the name and what it means to them
Maaaaaaaaybe talk to a lawyer
Listen to the actual humans, no matter whether they respond positively or negatively
Make sure you can get any necessary accounts
Write down the meaning and history of your project’s name before you forget about it

In short, we’re going to go through a due diligence process before finalizing a name for a new project. Some of these steps can happen in different orders, but I want you to check off every item on this list before buying another sweet domain name.

And if you’re worried that these rules will eliminate all the good domain names, rest assured that isn’t an issue. Let me put it this way: despite following these steps, I still own way too many domain names.

Check for how this name may be used elsewhere

Checking how a particular name is used can be as simple as running some online searches. Start with Google or DuckDuckGo or whatever flavor of search engine you prefer. Go a couple pages deep into those results. Depending on the words you’re looking at, you may get a Wikipedia disambiguation page, which honestly does a lot of the work here for you. On a practical level, we want to make sure there isn’t a major module out there already under a name you want to use. Wikipedia tends to be more up-to-date about programming modules than a lot of other topics.

Do the same on Twitter, and click around to all those tabs that show up on the search page. You can look at what tweets mentioning your keyword are the most popular, usernames which include the keywords and so own. I’ve found that this is one of the easier ways to check both newly evolving words and to surface name collisions in other languages.

Go to Urban Dictionary, too. Before you actually type things into search boxes, though, I should definitely point out that Urban Dictionary is routinely NSFW. Twitter is also routinely NSFW, but for entirely different reasons. In this use case, you’re looking for NSFW terms that relate to your name — things that you may be too mature to respond to, but that other users would giggle at or find offensive. As such, maybe don’t assign this job to an intern or first-time contributor.

Basically, we’re looking for any terrible ways a bored thirteen-year-old can twist your project name. We can’t preempt every comment, but we do not have to make it easy.

Talk to actual humans about the name and what it means to them

Next, and this is probably the hardest part, I’m going to need you to talk to actual humans, starting with any stakeholders interested in whatever project you’re working on. Depending on what kind of project you’re naming, your stakeholders could include employers and their lawyers, contributors (including documentation writers, who will need to type that name over and over again until it loses all meaning), and all of your friends who will have to listen to you talk about this project incessantly.

You’re going to also want to check in with your potential users about your name. Spend just as much time on talking to potential users about naming as you do on more visual user experiences. Check how they spell the name when they hear it for the first time. Check how they pronounce it if they read the name before hearing it. This might sound like a marketing exercise, but it’s really a question of usability and accessibility. If a user can’t figure out how to spell a product name, they’ll have to deal with a high level of friction before even deciding whether learning about a given tool is worth scrolling.

Tempting as it may be to ignore asking anyone outside of tech, I want you to make a point of running of names past at least three people who don’t work in tech. If you’re headed home for a holiday visit, feel free to ask your family to talk to you about your name idea. You can never guess who will run into what information and interact with it. You certainly can’t control it — if you could, every member of my family would be banned from ever seeing the word “Bitcoin”.

Your family members count as one person in this case, by the way. You can probably assume that your family’s background is close enough to your own that you’ll want to make sure to get some other opinions. You want to talk to folks who come from backgrounds different than your own because they’ll help you predict responses to that name from more people.

Personally, I like to ask a kid about any names I’m considering. At the very least I will immediately hear any possible poop jokes about my name selection, long before any adult will work up the courage to discuss possible scatological references.

A person with a little distance from the project can also help you catch names that are hilarious to you but rely on insider knowledge. Sometimes those sorts of in-jokes confuse or exclude people, making it even harder to get up to speed with a new library. If you can’t explain the joke in the time it takes us to walk to wherever we’re eating today, your sense of humor may be too subtle for the rest of us.

One more note about humor: think about who you are making fun of. Punching up is funny. I feel comfortable snarking about Monty Python because the members of that comedy troupe have made serious bank and have legions of fans ready to talk about the good points of their careers. Punching down is boring. If I want to watch someone make jokes at other people’s expenses or use humor to be a bully, I can just watch the news.

Check in with folks who speak languages you don’t, along with speakers of different dialects. Python is used all over the world, in more than 150 countries, so you’re never going to be able to check against all languages, but do what you can.

Maaaaaaaaybe talk to a lawyer

Occasionally, a lawyer may be useful in this process. I am not a lawyer and therefore all I can say that there are very few situations in which I would personally feel the need to consult a lawyer before finalizing the name for a new project. It’s pretty much just edgecases, like wanting to use a name already claimed by a multinational corporation. Future Thursday may hate me for this, but any smaller legal issues are her problem. Do your own risk assessment, though.

Listen to the actual humans, no matter whether they respond positively or negatively

Why is listening a separate step? Because we don’t just want first impressions. We want to know what sort of connections endure. We want to know about those jokes that take people a minute to remember. We want to hear any “Oh crap do you know what that sounds like?” moments.

Make sure you can get any necessary accounts

On a purely practical level, you’re going to need to know if you can get domain names, GitHub repos, or any other accounts you might use. If you’re reusing a name that’s already been associated with one software project, you’re going to have to do a little extra running around before you can finalize your name.

Very few platforms have a system for aging out old accounts yet, so there’s no clear date when any software project is permanently inactive. Some open source projects go years between releases, with no real need to update a website or a Twitter account in between. You have to use your best judgement.

Check the old project’s materials for trademarks, copyrights, and other indicators of intellectual property. No matter how any of us feel about intellectual property laws, I think can assume none of us really want to get sued. It’s not impossible to unravel intellectual property from a defunct project. I have never found a name I consider worth that level of effort.

Luckily, since we’re already talking to humans, we can just add the person last known to be running a given project to the list: if there’s a maintainer listed or even a contact form, just reach out and ask what’s going on with the project. If it’s actually defunct, ask if you can have their domain names and platform accounts. Make it as easy as possible on the other person and offer to pay for any fees, like domain transfer fees.

Even if there isn’t a pre-existing project, domain names can be tricky. Anyone working on anything related to any of the items on that Wikipedia disambiguation page could have already bought the domain name you want. Luckily, most Python projects are targeted towards audiences familiar enough with the internet to not flinch at the sight of non-dotcom domain names, like .io. That opens up options. Options for more research, I mean: That domain name is assigned to a part of the Indian Ocean currently referred to by the name British Indian Ocean Territory. Previously, that area was known as the Chagos Islands, mostly to the Chagossians, who the British forcibly removed from the Chagos Islands in 1966. Oh, look, another terrible example of how names reflect colonization! Using a .io address means taking this information into account.

Write down the meaning and history of your project’s name before you forget about it

Lastly, PLEASE PLEASE PLEASE document at least a little information about your project’s name. Just stick it in your README or some other piece of your documentation where it’s easy to find. Your documentation is a great place to put information about your project’s name and why you chose it.

Write down the pronunciation of the name that you use, even if you think it’s obvious. If you really want to know why I started working on a Python-specific style guide, it’s because of PyQt. That’s four consonants in a row, just hanging out. I’m pretty fond of vowels, so I wasn’t sure at first how to pronounce PyQt. I googled it, but I did not have a lot of luck.

Address any potential issues right away. Make a note of what other uses of the project’s name that you’ll need to disambiguate from. Django documentarians might make a note about music, for instance, so that someone creating a Django plugin meant to be used by musicians will pick a name that will actually be searchable. Address any potential problems head on, as well. Including context about a location name, for instance, will let you make sure people know which Portland you live in.

Go ahead and tell any jokes that go along with your project’s name right there in the documentation. Humor is amazingly memorable, but we only get that memory boost when we get the joke. It’s okay if not everyone gets the joke at first — jokes are still funny after they’re shared.

Takeaways

Names matter, even names that have existed for hundreds of years
Maybe don’t use Monty Python as a key part of your naming conventions
Complete due diligence on any name you consider

What they don’t tell you about creating style guides

10. Jul
/
Speaking
/
No Comments

slide reading "Step One: Make a Style Guide. Step Two: ? Step Three: Profit!"

What they don't tell you about creating style guides

This text was the basis of my recent talk at Write the Docs NA 2018, mostly about the glory and greatness of creating your own style guides from scratch. It highlights some of the major lessons I’ve learned about writing style guides, because I really like style guides — like, a lot. I make style guides for my own personal projects which only I will ever work on. I also help make style guides for wider use, including The Responsible Communication Style Guide. My current project is a style supplement for people writing about the Python programming language, so you will almost certainly hear me complaining about disambiguation if you run into me in person.

I believe I’m among fellow style-guide enthusiasts if you’ve read this far, but let’s just go over a couple of givens for this article. First, style guides are amazing. They’re basically lists of style decisions your team needs to stick to while working on a project that you no longer have to keep in your head. When you’re writing with a team, sharing a style guide will help ensure you all write with a similar style. Readers won’t get confused by different spellings, editors don’t have to correct the same errors over and over again, and writers can eliminate internal debates about when to capitalize the word “internet”. Style guides aren’t limited to written content, either — there are design and coding style guides as well.

It’s easy to build up a whole bookshelf of style guides. There are references like The Chicago Manual of Style, industry-specific style guides like The Bluebook which covers legal documents, organization-specific style guides like The Microsoft Manual of Style for Technical Publications. Depending on the project you may need more than one style guide — you might use an internal style guide when you’re writing documentation, then need to grab something broader to look up what your internal guide doesn’t cover. Sometimes you may need to even pull a more general guide off your shelf, like the Chicago Manual of Style. It’s a somewhat graceful deprecation, keeping the guidelines we need close at hand, with a fallback plan for anything an internal guide doesn’t cover. Those internal style guides are mostly what we’re talking about here — though I still have more space on my style guide shelf if any of you are thinking about something bigger.

Making your own style guide is a relatively easy process. RCSG started as a list of notes I kept for my own writing and then shared with a couple of other people as a template to adapt for their projects. That list turned into a book because it just kept getting longer. You too have the power to create your own style guide deep inside of you. I have faith in each of you.

A lot of developing a style guide is exactly what you think it is. You make a list of what you want to cover in your style guide, maybe words that you need to make sure you capitalize correctly or a list of the colors you should avoid for buttons. You keep adding things when you hear a new suggestion or make a novel mistake. Personally, most of my style guides are just a list of errors I’ve already made and reminders to not make them again. Seriously, I’ve already got a list of errata to update for the next printing of the RCSG because I’ve made new and interesting errors since the book went to the printers.

You edit your list, realize you’ve missed some things, edit again. You ask some people to read it and give you feedback, then you incorporate that feedback. At some point, you’ve got something you’re ready to share with a broader audience. Consider that version a first edition, because style guides are not carved in stone. You’ll start a list of things you want to update in the next version the moment you print a single copy, too. It’s not too different from other process documentation.

There’s no secret sauce when it comes to creating a style guide. You make the tool you need. There’s no magic software that will automagically pluck words from your documentation and shove them into a style guide. You can get the job done in a text file if that’s the only software available to you (though I encourage you to learn from my mistakes and move your style guide out of your word processing software of choice before it’s longer than five pages). A style guide can live within your other documentation or be available separately, depending on what you need.

The mechanics of putting together a style guide probably already feel familiar and I don’t want to spend too much time on them. Let’s talk about the major issues that come up when creating a style guide instead. There are three key sticking points we’re going to cover here:

Questioning assumptions
Bringing in unheard voices
Providing tooling and education

Question your assumptions

Sometimes I think that writing documentation is just a constant process of asking people to break down one step into smaller and clearer pieces. Everyone assumes that certain knowledge is universal. But unless we can develop species-wide telepathy, we can’t make that assumption. Every reader who looks at a piece of documentation brings their own experiences to interpreting it and may interpret it in an entirely different way.

That’s doubly true when working on a style guide. We can’t assume how other people use language. Consider the word “literally.” When I tell you that I am literally freezing, you know I’m cold. But am I actually literally experiencing a concerning drop in my core temperature? Not so much.

Despite my own feelings on the interchangeability of the words “literally” and “figuratively”, we haven’t just suddenly agreed to switch the meaning of a word out of nowhere. Different communities use different words in different ways. Language grows and changes to cover new concepts constantly, like how the word “computer” used to refer to a person making calculations, but now refers to a bunch of different types of devices. These changes are routine, through conversation, slang, academic use, memes, translation and literally every other time we communicate.

We can’t assume we know what someone means when they say “literally” anymore, at least without context. We need to ask.

I would go into a whole bit about user research here, but Jen Lambourne already said everything I was going to say, plus quite a bit more, so I’m just going to refer you to Jen’s talk at Write the Docs 2018 and keep talking specifically about style guides.

Ultimately, the more you can question your own assumptions around the meanings of the words you’re trying to define, the better equipped you’ll be to create style guides that speak to everyone. Jargon, acronyms, idiom, and slang may all have their place in writing — especially within technical writing — but only as long as they improve our ability to communicate.

Examine the status quo

That’s a side benefit of creating a style guide to share with other people, by the way. To create a good style guide requires asking questions about the status quo. If your documentation is all in advanced technical jargon, developing a style guide is a chance to ask why. If there isn’t a reason, style guide development will also offer an opportunity to make some changes to the way your organization communicates.

Many people won’t argue with a style guide once it’s established. I would never encourage any of you to use this fact for evil. For good, though? It’s an opportunity to advocate for changes to the status quo. When you’re making or updating a style guide, you get to choose whether to capitalize the word “Internet.” You also get to choose how members of your organization refer to people, what metaphors are considered inappropriate in your materials, and whether images must have alt text tags. Each of these decisions is an opportunity to create a more inclusive organization as much as a way to coordinate the voice of your organization.

Of course, you should go through all the appropriate approval channels before implementing a style guide, and of course, you should work with your team to make sure decisions are acceptable to as much of your organization as possible. You can adapt and update your style guide as appropriate for your organization.

But that one dudebro in your office who refuses to give you input during the process and then wants to know what they can do to change the whole style guide after the fact? Yeah, for that dudebro, your style guide has already been sent out to be chiseled in stone. Sorry, dude.

I should also warn you about the danger of swinging too far in the opposite direction. While requiring writers to match an organization’s voice and style makes sense, style guides are not meant as ways to police other people’s tone or voice. There is no one true way to write in English and we should only attempt to describe how to use language in our own context. We need to empower writers to do better. It’s never our job to tell people they’re writing incorrectly At best, I’d consider any attempt to enforce particular ways of writing or speaking to be classism. At worst, doing so is a well-established and particularly destructive method of colonization. It also results in bad writing.

So, yeah, writing a style guide is more responsibility than it might look on the surface. Pulling together lists of words and styles isn’t nearly as hard as understanding the impact of a style choice. We have an obligation to take extra care when developing style guides, especially those intended to be used by a diverse audience. We need to balance the voice of the organization with the voice of the writer. We can clarify how we communicate, without policing other people’s writing in a problematic way.

Bring in unheard voices

Empathy is the best tool we have for building effective style guides. We need a lot of compassion in this process, too. We need compassion for our users — the people who will use this style guide to write documentation — but we also need empathy for our users’ users — the people who will read the documentation our users write. Finding enough empathy may be the hardest part of writing a style guide.

Hopefully, you can find compassion for fellow writers, whether they write documentation full-time or write on top of other responsibilities. To empathize with your readers, you need to make sure that you have an understanding of the many backgrounds your readers may come from. I’m not just talking about understanding if someone has the technical know-how to get through your documentation. I’m talking about understanding cultural context around the words we use and repurpose for technology. I like the example of the Chevy Nova. According to urban sales legends, the Chevy Nova sold poorly in Latin American markets because “Nova” means “doesn’t go” in Spanish. Snopes has disproved this story, but I still use it because all of the actual examples I could use require content warnings.

We’re all aware that listening is a key skill for documentation. We know that we need to listen to as many people as we can who create, consume, or otherwise interact with the materials. But there are still voices we can learn from who we fail to hear. We need to listen to programmers with dramatically different backgrounds. I know how to write for the 20-something dudebro with a computer science degree, but I don’t know if the same materials will work for a single parent trying to learn to code in between taking care of kids. The only way to learn is to listen to people who are not in this room. If we want to build a truly inclusive industry, we need to meet the needs of people who haven’t been able to join us yet. We need to go out and find them.

You won’t be able to ensure your style guide is all things to all people. Starting with the intent to listen, and iterate on feedback on as it comes in is the right place to start, though. Include the people you already have access to — as many editors, sensitivity readers, beta testers, and users as you can practically manage — and build on that base to include new voices as you find them.

Pro tip: Inclusion during the development process also gives other members of your organization a sense of ownership and improves the likelihood they’ll use your style guide when it’s complete. It’s nice when doing the right thing makes your life easier.

Empower community members

And, of course, what’s the point of a style guide that no one uses? I feel like there should be a good punchline here, but there’s not really a joke. There’s no value in a style guide no one will use.

The best style guides empower their users. In my ideal world, I could hand anybody a style guide and some workflow documentation and they’d immediately be able to contribute to a writing project. That might be a little utopian, but it’s not as far off as you think. Consider Wikipedia. The site’s Manual of Style is somewhat buried, but the editing FAQ is a mini-style guide, covering things like link formatting and how to write article summaries. It’s more than enough to get someone started on their first Wikipedia edit. The Wikipedia Editing FAQ is a gateway style guide. It empowers people to make immediate changes.

Honestly, you’ll know your style guide is top-notch when someone outside of the docs team can hate-edit inaccurate documentation without needing to talk to an editor. I can tell you from experience that most style guides and contributor onboarding systems are not at this level.

Provide education and tools

Ultimately, a style guide should democratize the writing process in your organization. Style guide users should be able to write more clearly without relying entirely on editors or experts.

That’s a big “should.” There are a lot of assumptions there — and since we’re questioning our assumptions, we need to unpack that “should.” All other things being equal, a style guide should democratize the writing process in your organization. Those other things are the tricky part, though. We can’t just hand people a tool and assume everything will be fine. We need to educate our communities on how to use those tools.

Planning for education needs to be a part of your style guide development before you ever look up your first acronym. For experienced documentation writers, that education may mean a short workshop on the specifics of *this* style guide, while other users may need more of a “Style Guides: How do they Even” class. Ideally, someone should be able to pick up a style guide and use it without a class but given that very few people seem to read style guides all the way through, personal walkthroughs is a really good idea.

I like to start my educational plan with materials on how to contribute to new iterations of the style guide, by the way. The more people who can add to and improve a style guide, the more the workload is spread out, which isn’t exactly altruistic but is a necessary practicality.

If you can create a culture of contribution for your style guide from the start, you’ll enable improvements you can’t imagine ahead of time. Go beyond writers, too — if you’ve got a developer who needs to write at least some of their own documentation, giving them access to your style guide files can let them build tools that work for them (and that might work for you, too).

Don’t fall into the trap of thinking of a style guide as a book or a handout. Digital style guides put information in a wider variety of hands and create a world of potential right now, from providing a basis for new kinds of linters to upgrading spellcheck to something far more useful. Imagine how great the future will be if we make all of our style guides available via API!

Move the Overton window

Style guides represent the future, whether we know it or not. They streamline production processes and give people power to work on their own projects.

They also give us the opportunity to talk about how we write and why. Those discussions have the power to change the world. Style guides offer a clear indicator of how an organization wants to discuss different questions. A style guide that cautions users against terminology that some readers will find offensive is an explicit Overton window. An Overton window is a guide to what we consider appropriate to share in public discourse. For example, women wearing pants in public was considered highly inappropriate — until the Overton window moved as more and more people decided pants are perfectly reasonable apparel.

Our communities, both technical and not, are facing big questions about what we want to look like in a year, in five years, in ten. Within technology, many of these big questions are about inclusivity. Some communities have hard-coded styles of communication that exclude everyone who hasn’t personally written a programming language. Some communities want to make sure that the benefits of technology are available to everybody. The ways we style materials dictates, in part, what side of the divide our organizations land on. The more tools we have to create inclusive documentation and other materials, the faster we can move the Overton window towards expectations of respect and inclusion, at least within our own organizations.

I’m not expecting anyone to go back to work just to lead a style guide based-revolution (though if you want to, I’d love to hear about it). I am hoping, though, that you’ll start thinking about how you style your own work and whether a style guide will help your organization communicate more effectively.

I’m hoping you’ll think about the cultural assumptions that go into a style guide and how to give a voice to more people in your organization.

I’m hoping you’ll think about the communication status quo on the projects you work on and whether that status quo is effective.

I’m hoping you’ll drive big conversations about the future of our communities and how to welcome more people to those communities.

To sum up: style guides are awesome.

You should make at least one style guide in your life, if only so I have more people to commiserate with, I mean talk shop with.

When you’re making style guides, consider the assumptions you make, how you can empower the people who will use your guide, and what you hope the future brings, at least in terms of communication.

Lastly, making a style guide is an awesome responsibility. It gives you the opportunity to guide conversations, defeat miscommunications, and maybe even inspire newcomers to your communities. Subtle, yes, but style guides are powerful — and with great power comes great responsibility.

You can watch me give the original version of this talk at Write the Docs here, with bonus digression into why peanut butter isn’t the All-American treat we think it is.

You can buy a copy of The Responsible Communication Style Guide here.

Styling for inclusion: how shaping a style guide shapes our discussions

12. Apr
/
Speaking
/
No Comments

This talk was given at AlterConf PDX. You can see a video of the talk here:

I want to talk to you about the word “literally” for a moment. When I tell you that I am literally freezing, you know I’m cold. But am I actually literally experiencing a concerning drop in my core temperature? Not so much.

Despite my own feelings on the interchangeability of the words “literally” and “figuratively” (and do I ever have some opinions!), the reality is that we haven’t just suddenly agreed to switch the meaning of a word out of nowhere. Different communities use different words in different ways. Language grows and changes to cover new concepts constantly, like how the word “computer” used to refer to a person making calculations, but now refers to a bunch of different types of devices. These changes are routine, through conversation, slang, academic use, memes, translation and literally every other time we communicate. There is a reason English has a reputation for rifling through other languages’ pockets for loose nouns!

Trying to stop the growth of language is like shouting into the wind. Even if it makes you feel better, it’s not effective. And, honestly, most attempts to control language come with a lot of elitist and biased crap. (The history of the word “ain’t” is a basically a primer on classism and language.)

We make plenty of tools to help us write and communicate, from linters to dictionaries. We create tools to make sure we get job titles and other details right. But those tools can be tools of oppression. When a journalist relies on references recommending obsolete, oppressive, or offensive terms as standard, they’re going to use those terms. It’s the easiest option, just like using someone’s deadname is easier than researching and respecting someone’s identity. Their audience will use those terms or approaches, too, because an authority just used them. There’s a ripple effect when we rely on tools created without considering their use and impact.

We can see this in actual examples from actual tools: There’s a particularly awful example that The AP Stylebook updated last year. While “child prostitute” or “teenage prostitute” used to be acceptable under AP style, in 2016 the guide was updated to suggest that writers avoid using the word “prostitute” for anyone under the legal age of consent. That’s because the word “prostitute” implies a sex worker who is “voluntarily trading sex for money” and someone under the age of consent, by definition cannot voluntarily participate in sex in the first place, according to Tom Kent, one of the editors of The AP Stylebook.

The AP Stylebook will definitely have more updates in the future, from new technology terms to updated discussions of sports statistics. In fact, that’s their entire business model: journalists are encouraged to buy a new copy every single year. Most of us only update our copies every couple of years, but we’re used to thinking about at least this one specific tool as something that needs to grow and change with the language it describes.

That assumption of change is really useful when we talk about how to improve the systems and tools we rely on. It provides a framework where we can find ways to do better, ways to update our expectations as we learn, ways to improve on our communications. Sometimes it takes more time than we like to make these changes. (It took the Associated Press until 2016 to agree with the rest of us that “internet” shouldn’t be capitalized.) As it happens, though, there’s nothing to stop you from opening up a text doc and writing your own style guide. I’ve been doing that for years, which led me pretty much directly to giving this talk.

Writing about people is hard and I’ve messed up more than once. I’ve learned a lot of what I know at the expense of the people I’ve written about, because the tools I relied on were crap in one way or another. I started keeping a pre-publication list of everything I need to double check on every project because I misgendered an interview subject I only knew through email. I made an assumption and pushed publish. A few hours later, I got an incredibly kind email from that person pointing out my error. I apologized, but that wasn’t enough. I never want to make that error again, so I added a step to my workflow to ensure that I’ll do better.

I try to do good work, but I’m sure I’ll make more mistakes in the future. When I do, I’ll apologize and try to find a way to do better. That, as Kronda has told us, is the job.

For me, part of that process has been creating The Responsible Communication Style Guide. Basically, I wanted to take all of my tools and tricks and put them in a reference manual so I could improve my own work. Then I realized that sharing this sort of guide could help a couple of my fellow writers avoid making similar mistakes and that I could do some research to answer some questions I still had.

Then — and this is the most important thing — I realized that writing this style guide by myself would be a huge mistake. Just like the top-down approach at organizations like the Associated Press, writing everything would be a way to guarantee that I got something else wrong. If we want to guarantee that our work is inclusive, thoughtful, and responsible, we need to create it in inclusive, thoughtful, and responsible ways. Sure, I had a list of questions, but I didn’t have useful answers.

But I sure wasn’t going to ask anyone to work on fixing MY writing for free. So I worked with The Recompiler to run a Kickstarter. We met our goal mere hours before our campaign ended, giving us enough money to pay contributors and cover printing costs. That’s basically it. Folks, do not expect to get rich writing style guides.

But we did pay our contributors! That’s one of the pieces about this project that makes me the happiest. One of the most wonderful feeling in the world is to say, hey, you, you’re awesome and you know stuff and would you please take this money right now? I strongly recommend it when you need a serious pick-me-up. Keep this recommendation in mind, though, because I’m about to have some feelings up here.

Usually I have to talk about my work in a way that will convince everyone in the audience that they should pay for me to keep doing it. But in this room, I see people who not only have done that (thank you!) but who have helped me to do work that I consider important. That makes me feel like I have a certain amount of freedom here. So I want to say a couple of things in conclusion.

I don’t think I’m the right person to have edited this style guide. I’m just a person who had the willingness and the time to do so. Focusing on this work, running a Kickstarter to fund it, and not relying on this book as my main source of income is incredibly privileged. I’ve tried to stay aware of that privilege throughout the process of making The Responsible Communication Style Guide a reality. The most effective strategy I’ve found is paying contributors, so that people other than me can afford to work on this project. It’s not a solved problem in any way, though, just like everything else about this project. We had several potential contributors who weren’t able to work on this project because we couldn’t pay enough to make this project a top priority.

I want to acknowledge that I don’t consider The Responsible Communication Style Guide complete. I have lists of improvements to make in upcoming editions, topics we need to add, and experts I need to pay. The first edition is just that. It’s a first iteration to at least give us a starting point to improve upon as we learn more and try new approaches.

Given that we live under capitalism, the standard solution to both of my concerns is more money. I have to admit that I’m not optimistic about either capitalism or getting money for important work right now. Several communities I love are shutting down or scaling back right now, because there’s so little cash to be had. Even this conference today is bittersweet because I know there’s only one AlterConf left after this.

For the organizations that have the most money to give, things like diversity and inclusion aren’t a priority. When a inclusivity project can’t raise for $10,000 from an organization that spends that much just on “unisex” t-shirts, there’s something wrong. Sure, there are always organizations looking to buy diversity and inclusivity indulgences, but they don’t put money into it in the long-term.

You’re in this room. You probably already know all of this. But I want to ask you to do something when you go back to work next week. Go ask your employer to spend some money, preferably from outside some poorly-funded D-and-I initiative. Do the same thing next week, and the week after. Look at technical training budgets, continuing education credits, even the budget for holiday parties. Look for ways to move that money into the hands of people doing good work.

Helping plan a party? Pick a catering company operated by a person of color.

Need CE credits for a professional certification? Check if there are CE trainers for your certification focused on accessibility.

Got a technical training budget? Choose the trainers who subsidize community work with technical training.

I’m not asking you to seize the means of production, but I am asking you to redirect the means of production every chance you get. I know that isn’t a particularly inspiring message, but it’s the one I’ve got right now.

On that cheerful note, the last thing I want to do while I’m up here is acknowledge all of the people who have worked on The Responsible Communication Style Guide. I can’t name all of you in the time I have left, but I want to thank Audrey Eschright, our publisher, as well as our contributing editors Stephanie Morillo, Ellen Dash, Heidi Waterhouse, Melissa Chavez, and Anat Moskowitz, along with our designer, Mel Rainsberger. I may have done most of the cat-herding on this project, but there literally would not be a book without these people.

Put Your Damn Money Where Your Mouth Is

Diversity is important to tech, right?

We want the makeup of our company to reflect the vast range of people who use Twitter. Doing so will help us build a product to better serve people around the world. — Twitter
Intel is committed to setting the industry standard for a diverse and inclusive workplace culture. — Intel
At Facebook, we value the impact that every individual can have. We are dedicated to creating an environment where people can be their authentic selves and share their own diverse backgrounds, experiences, perspectives and ideas. — Facebook

Most of these companies have backed their words with money — funds that are earmarked for improving diversity. And they do back some good things, like events specifically meant for the demographics those companies are trying to add to their own workforces.

But the money that most tech companies have set aside for diversity isn’t going towards the infrastructure necessary to truly create a sustainably inclusive tech industry.

I’ve been an organizer with the local PyLadies group for a few years now, and we have no shortage of companies that want to buy us pizza so that they can tell our members about job opportunities. When someone talks about offering childcare at broader meetups, everyone agrees that the idea is sound, but no one wants to pay for it. The same is true for tech conferences. As co-chair of Open Source Bridge this year, I hoped to find a sponsor specifically for childcare — a simple change that would make it easier for attendees with families. The business case seems pretty obvious: no matter their gender, senior programmers routinely have families. If those programmers work remotely, are single parents, or split care with another parent, finding childcare can be difficult. Weekend conferences, in particular, can be hard because a parent might have to leave their children with someone overnight.

Providing childcare means that parents are more likely to attend conferences or other events and therefore have a better chance of interacting with a recruiter for a given company. That sort of infrastructure dramatically improves the number of people able to attend.

Adding infrastructure like childcare services to the technology industry’s norms is a prerequisite for making the industry more diverse. Recruiters have to be able to find diverse candidates if they’re going to connect them with employers. That means funding the infrastructure that gets those diverse candidates into the room.

So why is it so hard to get sponsors for things that make diverse conference attendance easier, even for relatively inexpensive additions like providing ASL interpreters?

I offered myself up as a walking billboard in our crowdfunding campaign in order to cover our childcare costs at Open Source Bridge. I asked numerous sponsors if they would be interested in being our childcare sponsor. The lack of enthusiasm compared to our standard sponsorship levels and even compared to sponsoring diversity scholarships was obvious. (Surprise: Even guaranteeing that a company get their logo on one of the most visible people at a given conference isn’t enough to get money for childcare. We managed to cover the cost of childcare, but it was a near thing.)

Apparently the name on the label is very important to sponsors: specifically labeling a sponsorship level as a diversity opportunity gets potential backers excited because they like having their names associated with the word ‘diversity.’

Don’t get me wrong. I’m all for diversity scholarships. They play an important role in making conferences more accessible. But each scholarship only helps one person. The right infrastructure will make tech events, along with the rest of the industry, more accessible to a much larger number. I may be hung up on childcare, but by offering childcare at no additional costs makes a world of difference for people who can afford a ticket to a conference but can’t afford the $100+ cost of a babysitter for a single day . For instance, think about developers whose employers will pay for their ticket and travel but won’t cover any other costs. And when you consider that multiple attendees will face that sort of expense, eliminating the cost of childcare means multiple attendees will find a conference financially accessible.

From a strict business perspective, this is ridiculous. And it’s easy enough to fix, provided tech companies truly want the diversity they keep talking about.

It’s time for tech companies to put their money where their mouths are.

In terms of conference sponsorships, that means funding real accessibility. The bullet points below are my personal wish list for conferences I run, but every conference needs different things:

An accessible venue
On-site, free childcare
Transcription and ASL interpretation
Multiple food options, including at snack times (vegan, halal, etc.)
Swag other than t-shirts

(Liz Abinante has a more exhaustive list here.)

There are plenty of other opportunities to develop better infrastructure in the tech industry in general, too:

Scholarship funds (not just individual scholarships) for code schools
Dry (alcohol-free) parties and other events
Childcare for meetups and other networking events

Dry events, in particular, would be a welcome addition. There is no doubt that the tech industry has a drinking problem. Even casual meetups often focus as much around a keg as they do around a technical talk. That excludes so many people: folks who have alcohol intolerances, folks who are pregnant, folks who need to drive home, and — perhaps the elephant in the room—folks who struggle with sobriety. An estimated one in 12 people have problems with alcohol abuse; they’re at every meetup, happy hour, conference, or other tech event we go to and have to face the choice of fitting in or taking care of themselves. And yet, many of these events don’t even have an alternative to drinking (asking for water can be difficult). We need not only alternative beverages, but alternative types of events that don’t rely on booze.

Because this sort of infrastructure doesn’t yet exist, many people are shut out of the tech industry. If you can’t go to the next networking happy hour for tech companies in your town — whether you can’t get a sitter, you can’t drink, or for some other reason — your chances of getting a job in the tech industry go way down.

A few people make it in anyhow, by paying what amounts to a tax on being more diverse than the next programmer over: finding a way to pay for whatever tools necessary to cover the cost of fitting in is the only way past those problems. In an ideal world, tech companies should give giant signing bonuses to candidates who improve their diversity numbers, if only to cover those candidates’ costs of getting into the industry in the first place.

The wage gap makes me think that sort of bonus will never happen, so pay for the infrastructure your company needs to recruit these people.

Want an easy way to start putting your money into the infrastructure the tech industry really needs? Cut a check to an organization today. Even $25 makes a difference, so if you benefit from that aforementioned wage gap, consider putting money in personally as well as through a company.

ThursdayBram.com