The Portland Charter Review Process: A Resource Roundup

I’ve been following the Portland Charter Review process closely since it started in 2020 and have done what I can to make the process a little more understandable. Those efforts have included Twitter threads, explainers, and even ideas for folks interested in submitting public comments. I’m collecting all the materials I’ve made here and will continue to add additional items as I make or find them.

Materials I’ve Created (Arranged By Topic)

Public Testimony to the Charter Review Commission

Applying to Join the Charter Review Commission (Application Now Closed)

  • Application Explainer — During the process of selecting commissioners for the Charter Review commission, I created this explainer to help more people apply for the commission.
  • Twitter Threads on Applying — This thread covers material included in the explainer adapted to social media. The threads are on Twitter, but there’s also a PDF of the tweets included in the threads, because finding old tweets is difficult.

Additional Resources From Other Sources

Sharing Guidelines

If you are interested in sharing or repurposing any of the materials I’ve created around the Portland Charter Review, you’re welcome to do so. I’ve licensed the materials I’ve created under a Creative Commons Attribution 4.0 International License, meaning that I just ask you to keep my name on things I’ve written as you share them. I’m not necessarily worried about credit so much as making sure that folks understand that these are materials produced in my spare time and are not reviewed by anyone who is officially part of the charter review process.

Please let me know if you do repurpose or share any of these materials in a way that I can help promote. Examples include:

  • (Forthcoming) Portland from the Left — An interview covering the Portland Charter, as well as how the Review Commission could change the Charter
  • Eliot Neighborhood News — A reprint of the Public Comment Signup Explainer
  • Application Process Graphics — Social media graphics designed by Hawnuh Lee for the charter review application process, based on the Application Explainer

19 Reads I Recommend from 2019

Here are 19 works I read in 2019 that I am still thinking about. I’ve divided the list into fiction and nonfiction, but that’s the only organizing principle at work here. Please note that while I read these works in 2019, not all were published in 2019.

Fiction

  1. Gideon the Ninth by Tamsyn Muir — Novel (Content Warnings for violence, body horror, and a whole bunch of necromancy). Are lesbian necromancers in space your thing? If so, read Gideon the Ninth immediately. If not, reassess why you feel that way, then read Gideon the Ninth immediately.
  2. Programmer at Large by DRMacIver — Novella (Content Warnings for social anxiety, privacy, and discussions of gender. Based loosely based on the Qeng Ho from Vernor Vinge’s “A Deepness in the Sky”, DRMacIver explores updating millenia-old computer code alongside discussions of how society might evolve with computer mediation. You don’t need to have read Vinge’s work (and, in fact, I haven’t read “A Deepness in the Sky”).
  3. Operation Spring Dawn by Mo Xiong, translated by Rebecca Kuang — Novella (Content Warnings for human extinction). Xiong also examines a potential future, with the story of a super ice age playing out over tens of thousands of years. The story isn’t a happy one, but it is meaningful.
  4. This microfiction by O. Westin — Flash Fiction (Content Warnings for ghosts). This story is just a couple of lines long, so go read it. I’m not going to write a critique of a story that’s longer than the story itself.
  5. Sisters of the Vast Black by Lina Rather — Novella (Content Warnings for virulent illnesses, violence, and religion). Rather’s world-building in this novella is exceptional, with small details that elevate the story from yet another story of the aftermath of an interstellar war. 
  6. Hot and Badgered by Shelly Laurentson — Novel (Content Warnings for violence, smut, snakes, and ableism). Let me preface this item with a confession: I read romance novels of all kinds, including novels about shapeshifters. Especially about shapeshifters. There’s a certain level of absurdity that goes with the standard plots of shapeshifter romance novels which I adore. The pinnacle of that absurdity may very well be “Hot and Badgered,” in which a honey badger shapeshifter finds true love. 
  7. Ironheart by Eve Ewing and Kevin Libranda — Comic Books (Content Warnings for racism, violence, and ageism). Marvel’s “Ironheart” is just finishing a 12-issue run. Superhero Ironheart, AKA Riri Williams, is a genius who reverse-engineered Tony Stark’s Ironman suit when she was 15. She’s awesome, though enjoying her series may be hard if you don’t have at least a vague idea of the Marvel universe. Watching “The Avengers” probably covers the bare minimum of background knowledge.
  8. The Calculating Stars by Mary Robinette Kowal — Novel (Content Warnings for racism, sexism, natural disasters, and anxiety). The Calculating Stars won the 2019 Nebula Award for Best Novel, the 2019 Locus Award for Best Science Fiction Novel, and the 2019 Hugo Award for Best Novel. Kowal’s alternate history of the space race won those awards for a reason.

Non-fiction

  1. Malfunctioning Sex Robot by Patricia Lockwood — Article (Content Warnings for misogyny, sexism, and John Updike’s particular brand of weird sex writing). Lockwood’s review of a recent reissue of John Updike’s work is a truly beautiful piece of criticism. She sets the tone from the start, exclaiming “You don’t bring in a 37-year-old woman to review John Updike in the year of our Lord 2019 unless you’re hoping to see blood on the ceiling.” and slogs through Updike’s career with an admirable persistence. The article is probably better if you’ve read any of Updike’s work (watching “The Witches of Eastwick” doesn’t count).
  2. American Radicals by Holly Jackson — Book (Content Warnings for slavery, racism, sexism, and violence). “American Radicals” offers background on the organizations and activists who championed slavery abolition, universal suffrage, and a variety of other causes during the 19th century. Jackson provides the context that reading about these movements on their own just can’t provide. I enjoyed the book thoroughly. My sisters, however, may not have appreciated me reading this book because, when we watched the new “Little Women” movie, I kept wanting to talk about Louisa May Alcott’s references to transcendentalism. 
  3. The 1619 Project by Nikole Hannah-Jones — Interactive Website (Content Warnings for slavery, racism, and violence). The 1619 Project comprises essays, poetry, photography, and more — all of which are worth your attention. Hannah-Jones developed the project to observe the 400th anniversary of the arrival of the first african slaves in America. 
  4. Jurassic Emoji by Courtney Milan — Proposal. Milan is a phenomenal romance novelist, but her application for the expansion of dinosaur emoji options is a great piece of writing and even includes scrupulous research into the need for such emojis. Milan has also created a timeline, if you’re curious about the process of creating new emojis.
  5. The Israeli Black Panthers Haggadah translated by Itamar Haritan — Booklet (Content Warnings for Zionism and racism). Created in 1971 as a protest of the treatment of Mizrahi Jews in Israel, this haggadah uses the story of the exodus as a uniquely Jewish way to protest. 
  6. Being “Polite” Often Gets Women Killed by Scaachi Koul — Article (Content Warnings for murder, sexual violence, and stalking). Koul’s deep dive into the culture and communities of true crime podcasts is fascinating (kind of in the same way that true crime shows are fascinating). She uses the topic as a way to examine women-oriented media’s ability to cover the reality that women face violence at higher rates than men in our culture.
  7. Algorithmic Colonization of Africa by Abeba Birhane — Article (Content Warnings for racism, colonialism, and privacy). A discussion on the ethics necessary for new technologies, Birhane highlights the way startups are recreating destructive systems in digital form. In particular, the article highlights how importing technology means importing the ethics of that technology’s creators.
  8. You Should Have Asked by Emma (Content Warning for emotional labor and gender). Emma managed to sum up some of the feelings I’ve had about emotional labor. If comics aren’t really your thing, Zoe Fenson’s article, It’s so much more than cooking is also a good read.
  9. How to Hide an Empire by Daniel Immerwahr — Book (Content Warnings for colonialism, racism, violence, genocide, incarceration. If I’m being precise, I still have a few chapters to read in this book, but I’m already convinced that every American needs to read this book. I like to think of myself as fairly conversant in the history of this country, but Immerwahr surfaces new information and offers new context to the point that I feel like I’m relearning centuries of history as I read.
  10. How Desire Built One of the Best Information Archives Online by Thursday Bram — Article (Content Warnings for privacy and links to sites that may host explicit material). Since this is my list and I make all the rules, I’m allowed to include my own work. This article is probably my favorite piece of my own writing from this year. Basically, my editor let me write about information architecture, fan fiction, and how sexy stories set new expectations for privacy.
  11. Reasons and Strategies for Avoiding Obsolete Terms by Erin Grace — Article (Content Warnings for slavery and racism). Editing this article caused me to immediately change how I wrote about certain topics. Sure, I’m biased because I worked on the project, but reading this article improved my writing.

This is hopefully enough reading material to keep everyone out of trouble for the next few months.

The Whys and Hows of “A Haggadah of Our Own”

TL;DR

I’m excited to present A Haggadah of Our Own, along with an accompanying Host’s Guide. I’m making it available to download. You’re welcome to download it for free here. If you’re inclined to support the project monetarily, you can pay whatever you feel comfortable with.

This is the culmination of close to six months of work, including the Kickstarter I ran in December. I’m considering doing another print run in time for Pesach next year (2020), so keep an eye out for that later this year.

For those who are interested, here’s a deep dive into how this Haggadah was developed.

The words "A Haggadah of Our Own" with an illustration of a green olive branch bracketing the words

Choices

The goal of A Haggadah of Our Own is to offer an inclusive Haggadah for as many readers as possible in one volume. Inclusion is a broad term: Within inclusion, we can talk about what can prevent a person from accessing the contents of a Haggadah. We can also talk about whether the story of Pesach is told in words that make a reader feel excluded or disconnected.

I say “as many readers as possible” because different readers have different needs. Throughout the process of developing A Haggadah of Our Own, I had to choose which needs I could meet. This article lays out some of those choices and the context around them, as well as details about the processes I used to make those decisions. This is going to get pretty meta.

This article is also going to cover where I’d like this project to go in the future. A Haggadah of Our Own is not the last Haggadah I expect any of us to buy (though it will last you a while). Some of the approaches in A Haggadah of Our Own are experimental — as results and responses come in, I fully expect to be able to improve on this initial version. In the meanwhile, though, we’ve got a more welcoming Haggadah.

One of those choices was the level of religiosity in this religious text. Rather than perfectly parsing Jewish law, A Haggadah of Our Own focuses on the participation of all attendees. It’s primarily in a vernacular language (English) and offers alternative blessings for Jewish humanists. It’s not the Haggadah for some readers, of course: for some Jews, precise observances of Pesach traditions are a higher priority. The priority here, however, is inclusion. No one should have to prove that they are Jewish enough to participate in Jewish life.

A Haggadah of Our Own includes traditions from all over the world but has a bias towards those from Ashkenazi and Sephardic communities. The availability of Pesach materials from different Jewish communities reflects underlying divides among those communities. Frankly, Ashkenazim have a sort of Jewish cultural hegemony that routinely erases other Jewish identities. I worked to minimize that primacy within this Haggadah but was limited by the resources (especially research materials) I had. Furthermore, I’m Ashkenazi and favored Yiddish over Ladino, along with transliteration that reflects Ashkenazi pronunciation. I can justify that decision by saying that I’m more familiar with Yiddish and could find more editorial support, but I know that it’s a weakness in terms of our inclusivity and an area I want to improve in.

I also chose to include gender-expansive blessings throughout the Haggadah. The decision to do so was one of the hardest decisions I made during the development of this material. There are many different factors at play here:

  • Hebrew is a gendered language, meaning that words are grammatically masculine or feminine. Spanish is another example of a gendered language, which is evolving to provide more options. “Latinx,” for instance, is an alternative to Latino (which is masculine) and Latina (which is feminine).
  • While there are many proposals on how to update Hebrew, there isn’t yet a standard on how to do so. All of the options I reviewed are effectively experimental linguistics.
  • Hebrew’s linguistic history is complicated: By 400 CE Hebrew was only used for communication between Jewish communities and religious purposes. In the 19th century, Zionists revived Hebrew. Modern Hebrew is used in Israel today. Hebrew is the only successfully revived dead language. That means that each update to Hebrew must navigate millennia of history and bias.
  • I received conflicting feedback from sensitivity readers about relative comfort levels with these blessings. It was a crucial reminder that communities aren’t monoliths and required me to make a decision that addressed all of the feedback I received.

The result is that I expect to need to update these blessings in the future. As new approaches to updating gendered languages become available in the future, Jewish communities will develop new norms. In the meanwhile, though, we can’t ignore the discomfort of trans and non-binary attendees. I chose to include gender-expansive blessings after research and feedback, while adding context and linking to criticism within the Host’s Guide.

Lastly, I decided to keep the Haggadah itself as clear as possible, so that it can easily be used and expanded by as many communities as possible. Suggestions for implementation are in the Host’s Guide, because so much of that material is relevant in planning a seder, rather than conducting a seder.

Research

During the research process, I read dozens of Haggadot. I prioritized reading materials created by communities over those prepared by publishing houses because many of the professionally published Haggadot are similar.

I also spent a lot of time Googling the word “haggadah” in combination with different communities, accommodations, and negative experiences. I spent a lot of time looking at bad examples and reading criticism about how to fix those issues. Those updates were low-hanging fruit and I’ve listed the articles and authors in the bibliography below.

As useful as all of those research materials were, though, talking to actual people about their experiences around the seder table was crucial.

When researching and developing appropriate accommodations, I have to give specials thanks to Elea Chang and Melissa Chavez. I’ve worked with them on several projects and I’ve tried to reflect their dedication to accessibility best practices in this Haggadah.

Writing + Editing

Developing A Haggadah of Our Own was more about editing and updating than writing new material. On the other hand, the Host’s Guide is all new writing.

The Kickstarter allowed me to work with amazing editors and sensitivity readers, who really helped me bring this project to a level I couldn’t hope to reach on my own. If you ever get a chance to work with any of these folks, you should grab that opportunity. Check out their projects at the links below

A special thank you to my partner, who has helped at every step of this process, from crafting artisanal HTML to make my EPUBs work properly, copy edited basically everything, and doesn’t get financial compensation. In fact, he backed the Kickstarter, so he kinda paid to get to work on the project… that’s definitely true love.

Design

Because different people need different types of accommodations, I had to decide what needs to prioritize when designing the print and digital book. I knew from the start that I wanted to create a Haggadah that worked with screen readers. I also chose to focus on making the print version of the Haggadah visually acceptable.

The font used in the Haggadah is APHfont, a font developed by the American Printing House for the Blind. The font’s features include:

  • More even spacing between letters.
  • Higher crossbars.
  • No serifs.
  • Wider letters.
  • Heavier letters.
  • Underslung “j” and “q”.
  • Letters more open.
  • Larger punctuation marks.

I went back and forth quite a bit, debating whether to use a font developed for readers with dyslexia, but APHfont offered the best all around accessibility. I would like to offer at least digital copies adjusted to meed different accessibility needs, such as a version optimized with that font developed for readers with dyslexia.

Laying out a Haggadah comes with some special design issues, by the way: the only way I was able to correctly layout Hebrew text (which flows right to left, rather than English’s left to right) was by downloading the Middle Eastern version of Creative Suite. As it turns out, the standard edition doesn’t allow for flowing text right to left.

Hebrew and other non-Latin alphabets also present a challenge when using screen readers. Many screen readers don’t support non-Latin alphabets and those that do have some quirks. VoiceOver on Mac, for instance, does support Hebrew — but that means reading off each individual letter, rather than words. Within the ebook, those screen readers that don’t support Hebrew use transliterations. The pronunciation isn’t ideal, but that’s a future project. VoiceOver presented some other issues, as well, requiring a version of the ebook optimized just for VoiceOver.

I also originally planned to include more design elements. I underestimated the time I’d need to commission and layout art. I hit a point where either I could get art or printed copies and I chose to make sure I could send out printed copies. I hope to create a new version with added art in the near future.

Printing + Shipping

Printing locally is important to me, partially because I can go over and look at proofs. The locality is important because every project faces delays and usually winds up a little tight, so being able to go physically get the books and mail them is nice. Morel Ink, a Portland, Oregon-based printer, printed the Haggadot. In addition to being easy to work with, Morel is a women-owned, union shop that values community. They support local non-profits and community organizations, making me happy to give them money. And a special shout out to Libby at Morel, who made miracles happen.

I also owe special thanks to Audrey Eschright, who let me copy and paste The Recompiler’s shipping process. In case you’re wondering why return labels listed The Recompiler, Audrey printed my paid postage labels. While my printer offered mailing services, packing and shipping the books myself was cheaper. And when I say myself, I need to include my amazing sister who told jokes and put books in envelopes in between work shifts.

Copyright

Copyrighting a Haggadah is kinda silly given that most of the material is sourced from millenia-old stories, especially given the importance Judaism puts on sharing knowledge as widely as possible. But then again, I find a lot of copyright law pretty silly. Both A Haggadah of Our Own and the Host’s Guide are licensed under Creative Commons, allowing anyone to use this material for non-commercial uses without needing to ask first.

I chose a non-commercial license not because I’m against the idea of other people using this material in commercial settings, but because I want to be aware of such projects and can ensure that they have the same sort of ethos.

Money

I’m never going to run a Kickstarter again. I said that after the RCSG Kickstarter campaign, but this time I mean it.

I ran the Kickstarter because paying contributors of all kinds is super important to me. I did wind up with a little extra budget, due to not being able to integrate the art I was hoping for. As a result, I increased pay rates for sensitivity readers and editors. I also have a little money left over (after setting aside money for taxes) which I plan to use as the seed funding for a future edition with more art.

Future

I’d like to do an update for 2020. I’m not sure yet what that means. In particular, I’ll only do another print run with a pre-order sale. I do have some goals:

  • I’d love to be able bring in more people, with more perspectives
  • Make available in more formats. I’m hoping to just keep adding to the versions of this Haggadah that are available, such as a version that better accommodates readers with dyslexia.
  • Bring in Ladino — this is going to require money because I definitely need to bring in a subject matter expert with editorial experience.

Partial Bibliography

Articles

Dunn, Mason. “Four Questions About Trans Rights.” JewishBoston.com.

Gross, Lior. “Nonbinary Hebrew Project.” NonbinaryHebrew.com.

Shalev, Asaf. “When Israel’s Sephardic Black Panthers Used Passover to Decry Racism.” Forward.com.

Takács, Bogi. “Nonbinary Hebrew.” Twitter.com

Twitty, Michael. “I’m Dreaming of an … African American … Passover.” Afroculinaria.com

Ungar, Eli. “My First Racist Haggadah.” Jewschool.com.

Books

Angel, Marc. A Sephardic Passover Haggadah. KTAV Publishing House.

Barenblat, Rachel. The Velveteen Rabbi’s Haggadah for Pesach. VelveteenRabbi.com.

Biber, Benyamin. The Machar Haggadah. Machar.org

Broner, E.M. and Naomi Nimrod. The Women’s Haggadah. Harper San Francisco.

JACS. The Anonymous Haggadah. JB FCS.

Jewdas. The Jewdas Cut and Paste Haggadah. Jewdas.org.

JFREJ. #BLM Haggadah. JFREJ.com.

JFREJ. Juneteenth Haggadah. JFREJ.com.

JFREJ. Mixed Multitudes: Nobody’s Free ‘til Everybody’s Free. JFREJ.com.

Pearce-Glassheim, Elizabeth. Haggadah for Jews and Buddhists. Modern Haggadah Distribution Company.

RTI. The Revenge of Dinah. DePaul University.

T’ruah. The Other Side of the Sea. Truah.org.

Waskow, Arthur. The Freedom Seder. The Shalom Center.

Websites

Haggadot.com

RitualWell: Passover. RitualWell.com.

My Jewish Learning: Passover. MyJewishLearning.com.

Chabad: Passover. Chabad.org.

Download my Hanukkah zines here

I shared 8 zines on Twitter, one each day of Hanukkah. I’ve gotten around to scanning and posting. So here they are as a PDF.

Hanukkah Zines PDF

Feel free to print and share these zines for personal use, but please talk to meee if you’re interested in selling copies of any or all of these zines.

To cut and fold your one page zines, you can follow this tutorial — it has pictures!

I’ll try to remember to share these again next December, before Hanukkah starts on December 22, 2019.

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. 

Announcing the Portland Prospectus

I help with sponsorship at a lot of tech conferences here in Portland. Last week, someone even tried to give me money for a conference I’m not helping with because they assumed (correctly) that I knew how sponsorship worked for that conference. Apparently, I have a reputation.

I’ve had my own little cheat sheet on what tech conferences are happening when in Portland, along with who to talk to about speaking, sponsoring, and so forth. I realized I might as well pretty up that cheat sheet and make it available, since it will help sponsors work effectively with more tech events. So here’s what the Portland Prospectus contains:

  • My recommendations for getting the best value for your sponsorship money here in Portland if you’re hiring or marketing to developers, designers, and other tech industry professionals
  • A spotter’s guide to specialties and languages across different conferences
  • A list of the conferences happening here in Portland through the end of 2017 (based only on the conferences I have dates for)
  • Highlights of some local vendors sponsors can work with to amp up impact

Please note that I am not an organizer for most of these conferences and I haven’t necessarily talked to the organizers of each conference. I used information available online to create this document. If you see incorrect information, please let me know and I’ll update it right away.

I am asking you for your email address in exchange for this PDF. First, I’d like to be rewarded for my work, not just in creating this PDF, but also because I do a lot of free labor on tech conferences here in Portland. Knowing who is interested in sponsorship and how to reach you makes my life a lot easier, so, yeah, I’m charging you the currency I find most useful for access to my tools.

Second, I’m considering sending out an update version of the Portland Prospectus towards the end of the year. I plan to send out a notification of when the new version is up. I’m also considering sending some other updates, like information about when local calls for proposal close.

If you’re not in Portland, you’re still welcome to download this PDF and sponsor our local tech conferences. You’re also welcome to copy this concept for your local community — I’ll even give you some spreadsheet templates if you contact me. Then, please, send me a copy of your finished local prospectus!

Download the Portland Prospectus

* indicates required




Glitter, Radical Protests, and Tee Ball on the South Lawn.

Saul Alinsky’s Rules for Radicals

The whole book is a useful read, albeit a bit dated — it was published by a professional organizer in 1971. But Alinsky’s rules remain widely applicable:

  1. Power is not only what you have, but what the enemy thinks you have.
  2. Never go outside the expertise of your people.
  3. Whenever possible, go outside the expertise of the enemy.
  4. Make the enemy live up to its own book of rules.
  5. Ridicule is man’s most potent weapon.
  6. A good tactic is one your people enjoy.
  7. A tactic that drags on too long becomes a drag.
  8. Keep the pressure on. Never let up.
  9. The threat is usually more terrifying than the thing itself.
  10. The major premise for tactics is the development of operations that will maintain a constant pressure upon the opposition.
  11. If you push a negative hard enough, it will push through and become a positive.
  12. The price of a successful attack is a constructive alternative.
  13. Pick the target, freeze it, personalize it, and polarize it.

A Glitter-Infused Protest

Reading today’s headlines would have made Saul Alinsky proud: around 200 activists grabbed the national news cycle by holding a dance party. Of course, holding the dance party outside of the vice president-elect’s home in Washington, D.C. definitely helped.

A Brief Buyer’s Guide: Glitter

I do not like the aftermath of glitter. Glitter gets everywhere and stays there for approximately the rest of forever. Seriously, glitter is so good at adhering to things that forensic scientists have written lengthy odes to glitter’s value in solving crimes.

But we’re going to need a lot of glitter for protest dance parties in the near future, so let’s talk about the environmental impact of glitter. On Amazon, you can buy glitter by the pound for under $20 per pound (which I’m not linking to, because no one should have that sort of power). When you buy a pound of glitter, you’re buying a pound of tiny pieces of plastic you fully intended to scatter around. Glitter is really does stick around forever.

So we need to switch to the biodegradable stuff. Luckily, biodegradable glitter comes in a variety of lovely colors, perfect for adding that something special to your next protest. No word yet on what forensic scientists think of biodegradable glitter, though.

Fireworks, Another Bright and Sparkly Option

Every American Inauguration Day has been celebrated with fireworks. The president-elect is keeping the fireworks for tomorrow’s festivities, even though he fired Charlie Brotman, who has announced every American presidential inauguration since 1957, when Brotman swore in Dwight D. Eisenhower for a second term. Brotman also was the stadium announcer for the Washington Senators, as well as announcing tee ball games on the South Lawn of the White House.

via GIPHY

Download My In-House Style Guide Template to Use However You Want

I’m excited to share the template I use for creating in-house style guides, as a reward for The Responsible Communication Style Guide Kickstarter reaching $10,000 in backing. Want to really improve your company’s communications? Back the Kickstarter today!

TL;DR: Here’s the link to download my in-house style guide template: the style guide as a .docx!

Keep reading for some context!

Whenever I sit down with a prospective client to work on their content, I ask about style guides: Does the organization or project rely on a particular style guide? How do they enforce style guidelines? How do they update the style guide?

I get a lot of blank stares. That’s okay, because very few of the organizations I work with are founded by trained content creators. While I know that anyone who already has a style guide in place will be easier to work with, I don’t consider a lack of a style guide a problem — at least before we start working together. I do insist, however, on making a style guide before we start on any other content projects. I need a style guide before I can create new content, audit old content, or even decide on what belongs in an editorial calendar.

Creating an in-house style guide isn’t that difficult of a process, provided you’ve made a couple dozen style guides over the length of your career. Part of that is experience. Part of that is building a template that can be customized to different organizations quickly. While I can’t give you a self-serve package of my expertise, I can give you the template that I’ve built up over the past decade or so.

I’m sharing this document as a .docx so you can easily adapt it to your own ends. You’ll want to start by reading through the style guide and adding in the information your organization needs to reference regularly (like exactly how to spell, space, and capitalize your company name). After that, you can share it with your team.

Remember, your style guide is a living document. Whenever new questions come up, add the answers to the guide. Whenever your organization hires a new person or releases a new product, add them to the guide. Whenever a content creator screws something up, add the information they need to avoid future problems to the guide. Schedule a regular review to update and clarify your in-house style guide. This template, by the way, is also a living document. I keep adding information to it, tweaking it, and looking for ways to improve it.

You’ll notice that there’s some information about writing inclusively in this guide. If this is a topic you’re just starting with, I recommend reading the white paper I released with Recompiler Media on quick changes your marketing team can make to dramatically increase your audience (PDF!) with an inclusive approach. If you aren’t thinking about inclusivity, you’re probably reaching only a fifth of your potential audience. If you are thinking about inclusivity, you can take your content to the next level by backing The Responsible Communication Style Guide Kickstarter.

A Partial List of Style Guides Everyone Should Read

Before deciding to create The Responsible Communication Style GuideI 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 Amazon 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 Amazon 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 Amazon 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 Amazon 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!