Writing *about* Python: a style guide

Given how much I write about Python, creating a style guide for writing about Python was probably inevitable. With the support of The Recompiler, I’m pleased to present a new supplement for The Responsible Communication Style Guide: The Python Style Supplement. We’re also working on a supplement covering Age.

The Python Style Supplement includes:

  • How to write about Python
  • Reasons and strategies for avoiding obsolete terms
  • Python terms and definitions
  • A timeline of Python’s development
  • An index of Python enhancement proposals with a special focus on PEP 8 and PEP 20
  • An index of Monty Python productions

The ebook is priced at $6 and contains over 100 pages of Python-related goodness.

Since discussions of obsolete terms are showing up again in programming circles, we’ve released Erin Grace’s article on “Reasons and strategies for avoiding obsolete terms” on the RCSG website. Previously included in The Python Style Supplement, we agreed that this article is too important to make available only behind a paywall.

What they don’t tell you about creating style guides

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. 

STYLE GUIDE GIVENS style guides are amazing you should use style guides you should make style guides for your projects and organizations

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.

STYLE GUIDE STICKING POINTS questioning assumptions bringing in unheard voices providing education and tools

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:

  1. Questioning assumptions
  2. Bringing in unheard voices
  3. 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.

STYLE GUIDE-BASED REVOLUTIONS style guides empower contributors style guides inspire questions about the status quo style guides are the future

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.

STYLE GUIDE TAKEAWAYS style guides are awesome when you make style guides, consider assumptions empowerment the future style guides are powerful

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

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. 

A Partial List of Style Guides Everyone Should Read

Before deciding to create The Responsible Communication Style Guide, I spent years looking for a style guide that filled that niche. I didn’t find one style guide that covered topics like race and gender and health all in one place.

Instead, I found dozens of style guides, covering a huge range of topics. I compiled this list as a starting point for folks who want to explore these topics and who want to dive a little deeper.

This list is really just a starting point, though. For The Responsible Communication Style Guide, we’re going to focus on five specific facets of identity: sex, gender, race, religion, and health and well-being. Within each of those sections, we’ll suggest key words and phrases to use when discussing these topics. We’ll also have a set of essays giving broader advice about writing inclusively. Throughout this process, we’re using technology as a lens to focus our coverage.

Each section editor has lived experience with the topic they will cover, as well as experience with writing and an understanding of our intersectional approach.

And if you’re interested in helping us fund a new style guide that covers identity with an intersectional approach, check out the Kickstarter for The Responsible Communication Style Guide. (Pro tip: at the $15 level, you’ll get a digital copy of our new style guide so that you can use it in your own writing as soon as possible.

AAJA Guide to Covering Asian America

Prepared by the Asian American Journalists Association. Covers terminology for covering topics of interest to Asian Americans.

Highlight:

JAPANESE NAMES:

In Japan, typically family name first, personal name second. But in the United States, Western word order is common. Women’s names often end in -ko, or “child,” as in Michiko.

American Sociological Association Style Guide

(Link to Bookshop listing!)

Prepared by the American Sociological Association. Covers style and terminology used in the publications of the ASA.

Highlight:

Race and Ethnicity

The classification and terminology of race and ethnicity are complex and have changed over time. Avoid racial and ethnic stereotyping of groups. Authors using racial and ethnic terms should aim to be as specific and precise as possible when identifying a person’s origin or group. For example, Cuban is more specific than Hispanic; Japanese is more specific than Asian.

Apple Style Guide

(Direct link to PDF!)

Prepared for internal use at Apple. Covers brand and company-specific terminology.

connector

Use to refer only to an item that can be plugged into a receptacle (such as a slot, port, or socket). Use the following terminology: edge connector: the connector on the edge of a peripheral card; fits into a slot minicircular connector: an 8-pin connector [Don’t use mini-DIN.] plug: a connector with prongs or pins In user materials, describe connectors by their shape and size, by the icon that appears on the connector, or in another way appropriate to the context. The user should be able to identify the connector easily even if she or he doesn’t know the terminology. Chapter 2 Style and usage 38 Avoid obscure names such as power input unit in favor of more direct terms, such as plug. Don’t use male or female to describe types of connectors.

BuzzFeed Style Guide

Prepared by Emmy Favilla and Megan Paolone for BuzzFeed. Covers publication-specific terminology and style.

Highlight:

LGBT Identification:

• Unless you already know based on research, it should be standard to ask how people identify themselves: gay, bi, genderqueer, queer, trans, etc.
• A person can be trans WITHOUT also being gay or lesbian. Don’t assume.
• Use “cisgender” (rather than “non-trans”) to refer to a person who is not transgender.

The Christian Writer’s Manual of Style

(Link to Bookshop listing!)

Prepared by Robert Hudson for publication by Zondervan. Covers terminology and styles used by the Christian publishing industry.

Highlight:

you, You (deity pronoun, second person)

Lowercase the second person of the deity pronoun as you would lowercase the third person. An exception is sometimes made in books of devotion or prayer when the capitalized, second-person pronoun is used to address God directly. (For more detail, see “Deity Pronoun, The” as well as “thou, thee, thy, thine.”)

Disability Language Style Guide

Prepared by the National Center on Disability and Journalism. Covers recommended language with an emphasis on specificity.

Highlight:

Handicap/handicapped

Background: The Oxford English dictionary defines a handicap as “a condition that restricts a person’s ability to function physically, mentally or socially.”

NCDJ Recommendation: Do not describe a person as handicapped unless it is central to the story. Avoid using handicap and handicapped when describing a person. Instead, refer to the person’s specific condition. The terms are still widely used when citing laws, regulations, places or things, such as handicapped parking, although many prefer the term accessible parking.

Conforms to AP style

The Diversity Style Guide

Prepared by Rachele Kanigel, for the Center for Integration and Improvement of Journalism. Covers a variety of terminology; however, this style guide is sourced from a variety of other style guides, rather than in-house development.

Highlight:

gender-neutral pronouns

Some people don’t feel that traditional gender pronouns, such as she/her and he/him, reflect their gender identities. Transgender, genderqueer and other people who step outside the male-female gender paradigm often adopt new pronouns for themselves. If a person doesn’t identify as male or female, it’s best to ask which pronouns they prefer.

The Economist Style Guide

Prepared by The Economist for its writers. Covers publication-specific information and style.

Highlight:

Gender

Gender is nowadays used in several ways. One is common in feminist writing, where the term has a technical meaning. “One is not born a woman, one becomes one,” argued Simone de Beauvoir: in other words, one chooses one’s gender. In such a context it would be absurd to use the word sex; the term must be gender. But, in using it thus, try to explain what you mean by it. Even feminists do not agree on a definition.

Gawker.com Style Guide

Prepared by Lockhart Steele, Choire Sicha, and Gina Trapani for Gawker.com. Covers publication-specific information and grammar.

Highlight:

WORDS AND PHRASES THAT YOU MAY NEVER USE

A long list, sure, but it is topped by “interesting” and “funny” and “of interest.” If it’s funny or interesting, that’ll prove itself, and it’s actually not funny or interesting if you have to describe it as such. See also: “Arguably.” (Fuck no.) This list also includes “lede” and “hed” and other sorts of made up journo-words. Gag. Finally, do not ever suggest in your writing that you do not care about something, or are bored by it, or that you do not know about something, or that you are above it. If you don’t care, are bored, or are confused, or the like, don’t write about it. Or fake it. Nothing is more off-putting for a reader than arriving at a post pre-bored and pre-disinterested. No apologies, no regrets.

GLAAD Media Reference Guide

Prepared by GLAAD. Covers terminology for “reporting on lesbian, gay, bisexual, and transgender lives, issues, and stories.” Note, portions of this guide is sourced from the AP and New York Times style guides, rather than in-house development.

Highlight:

Coming Out

A lifelong process of self-acceptance. People forge a lesbian, gay, bisexual or transgender identity first to themselves and then they may reveal it to others. Publicly sharing one’s identity may or may not be part of coming out.

Media Takes: On Aging

(Direct link to PDF!)

Prepared by the International Longevity Center and Aging Services of California. Covers terminology for the “accurate portrayal of aging.”

Highlight:

Handicap

Not a synonym for disability; describes a condition or barrier imposed by society, the environment or by one’s own self; can be used when citing laws and situations but should not be used to describe a disability; for example, the stairs are a handicap for him

NABJ Style Guide

Prepared by members of the National Association of Black Journalists, including Jerry McCormick and Angela Dodson. Covers “terms and language usage of special interest or relevance to our membership and our community.”

Highlight:

African, African American, black

Hyphenate when using African American as an adjective. Not all black people are African Americans (if they were born outside of the United States). Let a subjects preference determine which term to used. In a story in which race is relevant and there is no stated preference for an individual or individuals, use black because it is an accurate description of race. Be as specific as possible in honoring preferences, as in Haitian American, Jamaican American or (for a non-U.S. citizen living in the United States) Jamaican living in America. Do not use race in a police description unless the report is highly detailed and gives more than just the persons skin color. In news copy, aim to use black as an adjective, not a noun. Also, when describing a group, use black people instead of just blacks. In headlines, blacks, however, is acceptable.

NIDA Media Guide

(Direct link to PDF!)

Prepared by the National Institute on Drug Abuse. Covers terminology for policy discussions, scientific discussions, and health discussions, as well as media resources.

Highlight:

Cognitive-behavioral treatments

A set of treatments that focus on modifying thinking, motivation, coping mechanisms, and/or choices made by people.

NLGJA Stylebook

Prepared by the National Lesbian and Gay Journalists Association. Provides terminology to improve “inclusive coverage of lesbian, gay, bisexual and transgender people, includes entries on words and phrases that have become common, and features greater detail for earlier entries.”

Highlight:

coming out

Short for “coming out of the closet.” Accepting and letting others know of one’s previously hidden sexual orientation or gender identity.

A Progressive’s Style Guide

(Direct link to PDF!)

Prepared by Hanna Thomas and Anna Hirsch for SumOfUs. Covers core terminology for progressive activists in order to combat discriminatory language. Note, Hanna Thomas wrote about her experiences creating the guide.

Highlight:

Disability

Most times there is no need to refer to a person’s disability, but when the need arises, choose acceptable terminology for the specific disability or use the term preferred by the individual.

Race Reporting Guide

(Direct link to PDF!)

Prepared by Race Forward, the Center for Racial Justice Innovation. Covers terminology for “reporting on specific racial and ethnic groups. Also includes terminology and practices to avoid.

Highlight:

Ethnicity

A socially constructed grouping of people based on culture, tribe, language, national heritage, and/or religion. It is often used interchangeably with race and/or national origin, but should be instead considered as an overlapping, rather than identical, category. See the section “Covering Key Issues with a Racial Lens” and the term “Racial & Ethnic Categories.”

Religion Stylebook

Prepared by Religion Newswriters Foundation. Covers “the major religions, denominations and religious organizations journalists often encounter.”

Highlight:

Bible Belt

Areas of the United States that are noted for a prevalence of strict evangelical Christian teachings, particularly in the South and Midwest. Writer H.L. Mencken coined the phrase in 1925 while reporting on the Scopes Trial in Tennessee. It can be considered offensive in some contexts so the term should be used carefully.

Style Guide for NASA History Authors and Editors

Prepared by Steve Garber for NASA History. Covers preferred language, units of measurement, and publication-specific information.

Highlight:

Manned Space Program vs. Human Space Program:

All references referring to the space program should be non-gender specific (e.g. human, piloted, un-piloted, robotic). The exception to the rule is when referring to the Manned Spacecraft Center, the predecessor to the Johnson Space Center in Houston, or any other official program name or title that included “manned” (e.g. Associate Administrator for Manned Spaceflight).

Style Guide: Reporting on Mental Health

(Direct link to PDF!)

Prepared by TEAM Up and the California Mental Health Services Authority. Covers preferred language and language to be avoided.

Highlight:

relevance

Do not assume that there is a link between an event that seems irrational and the mental health of someone in the story. Not preferred: “A man whose neighbors said he seemed depressed left his sprinklers on for days, leading to neighborhood flooding.” Preferred: “Sprinklers that appeared to have been left on for more than 80 hours led to damage in three nearby houses, water officials said.”

The Supreme Court’s Style Guide

(Link to Bookshop listing!)

Prepared by Jack Metzler with the Office of the Reporter of Decisions, Supreme Court of the United States. Covers terminology, cases, and styles used in Supreme Court decisions.

Highlight:

Repeating citations

(a) “Hereinafter” shortened form. If in the text or (more commonly) in a footnote frequent citations are to be made of a certain secondary source, it is often desirable to use a shortened form for the subsequent citations. This is generally done with a parenthetical that immediately follows the citation of the source and precedes all other parentheticals. Where a specific page is cited in the subsequent reference, do not then use “at” or “p.” Simply use the shortened form followed by the page number.

The Yahoo! Style Guide

(Link to Bookshop listing!)

Prepared by Chris Barr for Yahoo! and revised for print. Covers style for materials written for online publication.

No highlight available.

Looking for design or development style guides and pattern libraries? Start with these posts!

The Responsible Communication Style Guide: A Kickstarter and an Explanation

I’m working on The Responsible Communication Style Guide with Recompiler Media. This project is something I’ve been thinking about for years and I wanted to write up how I got to this place.

Our Kickstarter is here — backing at the $15 level is the fastest way to get a copy of The Responsible Communication Style Guide to use in your own work.

CONTENT NOTES

This post is over 2,500 words. There’s some heavy emotional stuff in here (lived experience + the Holocaust, how language affects our lives, and diversity in technology). I do hope you’ll read the whole thing.

How to Screw Up as a Journalist in One Easy Step

I screwed up early in my career as a freelance writer: I conducted an email interview with an individual named “Chris” for an article I was working on. In the article, I referred to Chris with a male pronoun. My source emailed me immediately after reading the article to say that “Chris” was short for “Christine” and that she would appreciate me fixing the error.

Chris was super nice about the whole thing, making me think that I wasn’t the first person to make this particular mistake. Now I do some obsessive Google-ing if I’m not sure how to describe a person just from an interview — though even Google can’t always tell me enough information.

Ever since, I’ve also been looking for a guide or workshop or some sort of education on how to ask questions about identity without being offensive. Sure, asking someone their pronouns is one of my standard interview questions (along with how to spell their name and what their professional title is), but that’s not enough.

  • How do you even begin to ask a trans person about referring to them by their dead name if you’re writing about them during a time when they still used that name?
  • How do you make sure that unconscious bias doesn’t influence your writing?
  • How do you write about someone engaged in activism without bringing an internet shitstorm down on their heads?
  • Heck, how do you even determine if you’re only telling stories about people like you or if you’re finding diverse sources or stories?

I don’t have the one true answer to all these questions. Figuring out how to handle these sorts of topics requires both empathy and context. Context, in turn, requires lived experience.

What is ‘lived experience?’ Lived experience, or the experiences, emotions, and impressions of a person living as a member of a minority, is easily dismissed as a buzzword from a women’s studies class. Hanging out in tech circles, I mostly hear people talking about their lived experiences and how they differ from what other people may see (such as a woman talking about an act of discrimination, only to be told by a man that he’s never seen any problems in the industry). While I don’t think that this sort of gaslighting should be dismissed, there are even bigger dangers to ignoring others’ lived experience: My paternal grandfather was a Holocaust survivor. He spent six years in concentration camps. When he was liberated in 1945, he was 18. He weighed 85 pounds. In the years that followed, my grandfather encountered Holocaust deniers. These people told my grandfather that the hell he went through never happened.

I don’t want to turn this blog post into an example of Godwin’s Law, but every time I hear someone discounting lived experience, I see them become a little more willing to accept anti-Semitism and other bigotry. Suffice it to say that I strongly believe in the importance of involving someone with lived experience when creating training materials about their identity, history, community, and other related topics.

Back to the Question at Hand: Improving Our Ability to Communicate

At the same time, expecting anyone (no matter their lived experience, expertise, or knowledge) to educate either individuals or organizations purely out of the goodness of their heart is both rude and unreasonable. My landlord doesn’t let me live in my apartment out of the goodness of its warm, fuzzy, corporate heart, so I need to spend my time in a way that gets my rent paid — and I expect the same to be true of every human I encounter. (Kronda Adair has written several brilliant posts on this topic — start with this post.) In the event we all wind up living in a communist utopia, remind me to revisit this point.

That means paying multiple editors to look over my work who can bring the right context to it, right? Since I don’t have a lot of money, I generally can’t afford to work with more than one editor on a project. As it happens, since I write for the web, I often can’t afford to work with even one editor.

When I’m flying without a grammatical net, there are some options for improving my writing without spending a ton of money:

  • I use a ton of technology. There are tools to analyze common grammatical mistakes, such as the spell check tool built into most word processors. But there are also tools that do more specific editing tasks, such as the Hemingway app, which helps writers to follow Hemingway’s writing advice (limited adjectives and adverbs, short sentence structures and so on).
  • I got an education in writing and communications, and then kept learning. I have a couple of degrees in communication, which included loads of classes on writing. I also still read a ridiculous amount about writing. I kept learning after getting a degree, using self-education materials available from experts, ranging from writing hacks to full-fledged textbooks. A degree isn’t necessary in this field and an in-person class isn’t even required.
  • Lastly, I adore my style guide. I don’t (usually) sleep with the AP Stylebook, but I still keep both the digital and print copies handy. I also own a bunch of other style guides. I ask the publications I write for if they have their own style guides. I also have made my own style guides, both for individual publications I work on and more generally (i.e., I’ll go to bat with an editor to make sure ‘internet’ is not capitalized).

The resources for writing responsibly and ethically are few and far between. During my education, the closest I got to a class on how to write with some level of sensitivity was a graduate-level course on how to write about controversial topics — where ‘controversial’ was read as ‘political’ or ‘religious’ more than anything else. (Side note: That class was taught by Arthur Magida, author of How to Be a Perfect Stranger, which I have referred to as The Book that Keeps Me From Screwing Up Other People’s Weddings. I highly recommended it.)

That particular class was incredibly valuable, but I had to wait until I was working on a master’s degree to have an instructor start talking about how to start thinking about dealing with difficult topics, despite taking my first journalism class in middle school. How is there not a basic class in every journalism, public relations, and marketing program on how to write for diverse audiences? We teach basic interviewing techniques, like how to ask a question to high school journalism classes, but fail to teach those same students which questions to ask or who to ask questions of. I don’t know what your student paper looked like, but mine didn’t exactly reflect the demographics of our student body. It reflected the perspectives of the teachers leading the class and of the kids in accelerated English classes — despite having a big ESL program at our school, I can’t remember a single ESL student writing for the student paper. I’m not advocating for fully restructuring journalism (yet!) but we do need to make a point of teaching empathy in journalism.

We’re at the beginning of conversations about representation in the media. There are a few organizations now that try to track statistics on authors and writers, like the VIDA Count. Getting more diverse writers (and other media makers) into big publications is just a first step. Telling stories of underrepresented demographics is the next step — and I’m not talking about tokenism. Pro tip: it’s perfectly fine to have an article about a technical project led by a woman without every asking her about whether she thinks tech is a tough industry for women. As a matter of fact, skipping the focus on how different the story’s subject is means that you get to spend more time on how cool the actual project is.

Some individuals and organizations have started working on this problem, but many resources are fragmented. I have more than a dozen style guides and media guides just for covering religion. (I’ll get more into what’s out there in another post I’m already working on.)

We still have a long way to go to get to a truly diverse media scene, though. I keep thinking of our current media landscape as the beginning of a very long journey — we’re still outfitting ourselves for the trek and don’t really know what’s on the trail ahead. We won’t even know some of the work we need to do to get to that far off Wonderland until we get on the road. We know that we need to remodel or replace many of the systems in place to produce journalism and other media, but until that work is done, we won’t know many of the steps that come after.

Let’s Talk Ideals and Infrastructure for Writers

In my ideal world, I could just use pronouns that aren’t based on gender for writing and everything else. I recognize that I have to stick to the current system if I want readers to be able to understand everything I publish, but I certainly don’t like the existing system.

Until there’s a good opportunity for a linguistic revolution, I’m focused on making the existing system better. That means starting with the writers who make the articles, blog posts, and other things we read (along with the scripts for plenty of the audio and video content we see, too). Style guides are a good starting point for talking about how we cover things because we’re already used to looking up details we might get wrong.

In fact, some organizations have put out specialized style guides for how writers can cover their specific communities. These resources are all over the place, however, and sometimes contradictory. Creating a standard resource is the first step to making improvements in who writes what stories. Having discussions about diversity and inclusion before publishing anything will, at least, limit some of the more thoughtless headlines and references that we see constantly. As a personal goal, I’d like to see publishers avoid referring to an Olympic athlete as someone else’s wife.

I have thought of other formats this style guide could take. I kept coming back to the idea of doing the research and running an in-person workshop, geared towards newsrooms. But while we clearly need more educational materials about writing responsibly, style guides have more power than classes. I’ve taken more writing classes than I can count. I don’t remember where all the handouts and notes are from those classes, though I can point to the occasional writing hack and say that I picked it up from a particular instructor. You could have swapped out most of my writing teachers for other writing teachers and I would never have noticed.

But taking my AP Stylebook from me would turn me into a mess. And while I could manage if you took my Chicago Manual of Style or one of the other style guides I rely on, I would be pretty unhappy. These reference books have impacted my writing far more than anything or anyone else.

Making a Real Difference with The Responsible Communication Style Guide

I’ve spent the past couple of years casually talking about making a style guide that answers some of the questions I have. Audrey Eschright, the publisher ofthe Recompiler, heard me talking about the idea for The Responsible Communication Style Guide this spring. She said that she wanted something similar and would be willing to work on the project.

Working with Audrey is amazing — we’re on the same page about everything except whether there’s a hyphen in ‘ebook’ (I’m anti-hyphen, while Audrey is pro-hyphen, if you’re wondering). Perhaps the most important thing we agree on is how to construct The Responsible Communication Style Guide. Our particular manifesto for this project can be broken down into the following bullet points:

  • We’re hiring the right people to write each of these sections and we’re paying them. None of that crap about asking people to educate us for free here.
  • We’re creating a printed resource, as well as a website. Different people use different formats (and we’ve got some cool ideas for even more approaches once we’ve got the initial iteration ready).
  • We’re developing training around The Responsible Communication Style Guide, because people only use resources they have some familiarity with.
  • We agree that this sort of style guide isn’t just about writing clearly. It’s also about being able to communicate in a manner that doesn’t harm anyone: writers, editors, and publishers influence culture and attitudes so directly that we have an obligation to use that power responsibly.

Yes, we’re both absolutely scratching our own itch with The Responsible Communication Style Guide. But we’re also creating something that we know there’s a need for — and something with the potential to guide major conversations in technology. Yes, journalists working in this space need the guide. But there’s more room than that in the long run. Ultimately, everyone in technology is a writer: a programmer writes documentation, technical blog posts, and internal talks, even if they never publish a single word outside of an employer’s media. Designers, marketers, and even business analysts create reams of written material every day.

This guide gives people who don’t necessarily think of themselves as writers a starting point for thinking, talking, and, yes, writing, about users in an empathetic way. There’s a real potential for The Responsible Communication Style Guide to equip us for important conversations by providing an introduction to concepts of identity and a framework for writing about those concepts.

So here we are. There’s a big chunk of my heart and soul up on Kickstarter right now. I’m a bit terrified, especially of getting things wrong with the people who I want to contribute to The Responsible Communication Style Guide. I’m ridiculously hopeful about what bringing this project to life means for the books and blogs I’ll read in the future. I’m wound up waiting to see who will back this project. We’ve got just under a month to make this happen. Let’s go.

We Need Your Help

If you are as excited as I am, we are looking for help!

  • Please consider backing our project, even at a low level. If everyone just bought an ebook copy at the $15 level, we would need just over 1,300 backers — and there are far more than 1,300 people writing about these topics.
  • Please share our Kickstarter with everyone who you think might be interested. From our perspective, that means journalists, marketers, speakers, and other folks who write publicly. But once the Responsible Communication Style Guide is a reality, we expect people to use it in ways we never considered.
  • Please let us know if you think of any ways to make this material more accessible to your community. We have some ideas (I want a linter for writing!), some of which will be incorporated into this first iteration of the guide and some of which we’ll work on after the Kickstarter (including my hopes for a linter).

Thank you for reading this whole long post and thank you for your help.