​Formally ending The Portland Prospectus

Some of you may remember that in the before times, I ran an email list covering sponsorship opportunities around tech conferences and other events related to tech here in Portland. I haven’t updated it since 2019, given the large number of cancellations and postponements in the last two years.

Both running and sponsoring events look dramatically different today than they did in 2017, when I started the newsletter. Personally, I don’t feel comfortable attending big events in person and I don’t see that changing any time soon. My work has also moved away from the tech industry, so I’m not really tracking tech events very closely at this point.

As a result, I’ve decided to formally shut down the mailing list. After this post goes live, I’ll delete the mailing list, including subscriber emails. If someone wants to start something similar in the future, you have my blessing. And if you want my templates and notes, let me know — we can work out an equitable arrangement.

Since I’ll be deleting the content that went out to the Portland Prospectus mailing list, I’m also sharing the PDFs of the different iterations of the Portland Prospectus here as a sort of archive.

My election coverage, to date

I’m already working on some coverage of the 2022 primary and general elections. In the meanwhile, though, I wanted to collect the resources I’ve made over the past several years into one place.

Prior to moving to Portland, I also wrote about elections (including a stint blogging professionally about the 2008 election). I don’t really recommend my political writing prior to about ten years ago; I have learned a lot since then and developed personal politics that I feel a lot better about.

Evergreen Resources

Election-Specific Resources

PyCon 2022 talk proposals (and 75 talk ideas you can use)

PyCon 2022’s call for speakers has a little more than a month left on it, so it’s probably a good time to note that one of my past proposals is one of the examples for how to pitch a tutorial (particularly if it’s not a technical tutorial). You can see my proposal here — it’s the second on the page. If you want to see the tutorial that resulted from this proposal, I’ve posted the script and video of the tutorial on my site.

As someone who regularly submits talks to technical conferences that aren’t really focused on technology, I found the feedback from this proposal especially helpful for future talks. Here’s one highlight that has convinced me to double-down on writing lengthier proposals in order to get my idea across:

Audience:

We especially liked the ‘audience’ section. The description of whom the tutorial was aimed at was excellent.

Most of our favorite proposals include clear learning goals (showing us what the audience will learn, and giving them motivation to attend). This one provides additional details, unique to the format of the tutorial itself:

“Attendees will have at least one writing sample they can share and will be better equipped to write and test their own materials, as well as evaluate others’ writing. They’ll also know about opportunities to share their writing with other pythonistas.”

I hope these materials serve as an inspiration for Python speakers, especially anyone considering putting in a talk that focuses less on the programming language itself and more on the context in which we use it.

And if you need ideas for topics that would make great talks in 2022, here are a list of ideas pulled from various Twitter threads I’ve posted over the years and updated as needed (2021, 2020, 2019, 2018). These talk ideas are, of course, not vetted by PyCon staff and are just talks I want to watch.

  1. Most of us have spent almost two years thinking about COVID vaccines almost constantly. Some places have done well at distribution, some are struggling. If you’re building or using Python tools to help with the vaccination effort, tell the rest of us. If there’s still work to be done, tell us about it so we can help.
  2. If you have any scripts or tools that make living a socially-distanced life easier, I think a lot of people are still looking for ways to make remote everything easier.
  3. A talk about writing Python with minimal internet access or writing programs for users with minimal internet access may seem like a counterintuitive idea. But many folks have precarious internet access, and the continuing pandemic leaves those folks with fewer opportunities to go elsewhere for better access.
  4. I’m not sure what the highest number of types of pythons you can reference in one talk, but I’ve seen some herpetology tools written in Python and there’s a giant prehistoric snake with the taxonomic name _Montypythonoides riversleighensis_. There’s a lot of material there.
  5. Was there some nuance about Python you struggled with this year? Write up an explanation — I promise that if you struggled with a Python concept, some other Pythonista has too!
  6. Are you working on one of the many elections happening in 2022? Empower your fellow Python programmers to take their skills and get involved in the political process.
  7. We need to talk about prisontech and how much technology works goes into maintaining white supremacy if we want to have even a chance of reducing structural racism.
  8. Las PyCon Charlas será un track de charlas en español abierto a toda la comunidad que tendrá lugar en la PyCon US. Si hablas español, ¿por qué no envías una propuesta de charla?
  9. With the current wave of unionization at a variety of tech companies, it’s time to talk about organizing in tech communities. Some folks may be starting out with collective action, so both introductory talks and more advanced materials are good.
  10. This is more a general topic for programmers, rather than just Pythonistas, but how about a talk on dealing with old computer hardware. Programs like Portland’s Free Geek do phenomenal work getting technology in the hands of those who need it, like students going to school remotely.
  11. As responsible consumers of data, why do we not talk more about how we dispose of data? Storage space may not be an issue, but privacy definitely is!
  12. Programmers need more education on how to mitigate climate change factors. Honestly, all I know off the top of my head is that Bitcoin produces more carbon emissions than the entire country of Argentina.
  13. What do you do if you discover that your employer provides, say, a connected thermostat to a client you don’t like, for instance, ICE? Holding employers to ethical standards is a skill set every programmer needs.
  14. There are Python newsletters, podcasts, blogs, books, and other media. Maybe it’s time to start talking about the Python media ecosystem. What would this talk look like? a guided tour through what’s out there? a discussion on how the different bits interact? There are so many options!
  15. Based on unfortunate mistakes that were made, possibly at my desk, I’d love to hear more from experienced folks on how to interact with other people’s projects in ways that won’t overwhelm a server or break other stuff. i.e. how to use an API run by a nonprofit with an all volunteer tech team.
  16. Fundraising for open source projects has changed dramatically in the last two years. PyCon, for instance, is usually the PSF’s main fundraiser. If you’ve successfully raised money for an open source project in the last year, we’d all appreciate you sharing with the rest of us.
  17. I have a dream of PyCon hosting its own fashion show some day. We deserve it. And Nina Zakharenko’s earrings deserve to be on the runway.
  18. What’s the absolute weirdest hardware you’ve gotten Python to run on? Currently, I think the Furby is a standout but I bet y’all can surprise me.
  19. If you struggled to learn any concept related to Python, consider giving a talk about that concept — I can guarantee that if you struggled with something, other folks in the Python community struggled too!
  20. I’ve seen dozens of tarot and astrology apps at this point. Getting a developer’s perspective of building systems that (I assume) need to work in an element of chance or intuition world make for an amazing talk.
  21. I’m getting kind of tired of talks on automation scripts for businesses. How about some household automation scripts? Did you write a script for generating a shopping list or managing chores?
  22. Have you tweaked Python IDEs & other programming tools to make programming in Python accessible? In the past, talks covered tools for programmers with low vision and teaching Python in ASL, but there must be other accessibility hacks worth sharing.
  23. I have seen some truly amazing Python-driven sensors for temperature, moisture, and other environmental factors. I have to believe someone has put them all together into an amazing gardening system. If you are that person, you should tell the rest of us how to do the same!
  24. I’ve heard more than once that Python is used on every continent, but what exactly are Antarctic Python users up to? That’s a talk I’d listen to, for sure!
  25. I think every conference organizer has seen several versions of “How to make your first contribution to open source”, so it’s time for talks about how to make your second, or third, or hundredth contribution to open source. Tell us what comes next.
  26. There are plenty of talks out there about programming with security in mind, but it’s a struggle to find anything about programming with privacy in mind. We have a responsibility to keep users’ information private, so we need tools and techniques to ensure that privacy.
  27. Finding data sets to train machine learning projects on can have unintended consequences. Any ML enthusiasts out there who can explain what to look for when choosing data sets?
  28. If we’re honest, we could all probably use a talk on how to create bug reports that will actually result in fixes.
  29. We clearly need a Python game arcade during the conference. I will happily bring a bunch of quarters if someone brings the games.
  30. Python has been deployed to help during several recent emergencies. What’s it like to use Python in those scenarios? Is there anything you’d do differently or wish you had in your toolbox?
  31. The National Oceanic and Atmospheric Administration has this lovely open data discovery portal. Let’s talk about the weather (especially the growing number of extreme weather events).
  32. There’s one poster that I would love to see: a guide to what Python programmers are expected to know at different experience levels, at least in terms of what hiring managers are looking for.
  33. Building a Python app can be a matter of hours — but scaling that same app could take the rest of your life. If you’ve gone through the process, please let the rest of us learn from your experience.
  34. IoT / connected devices have enabled a lot of people to customize their homes to better suit their needs, like by using lights to create visual warnings for folks who can’t afford fully accessible alarms. Talk us through what that sort of project entails.
  35. Given Python’s educational usage, we may need to spend more time on Python’s user experience. I’m not sure if this topic would be best as a talk or as an open space.
  36. Several open source communities have experienced controversies over limiting the use of their work based on ethical concerns. It seems worth discussing what ethical concerns Python contributors have, as well as what Pythonic ethics might look like.
  37. Using Python to change your online browsing experience (i.e., filtering out abusive content on reddit) could make for a great talk.
  38. I would love to know how to effectively assess libraries and frameworks when choosing how to build a project. How do you vet tools so you avoid components that won’t be supported a year from now?
  39. Can someone demo some hiring exercises that don’t require whiteboarding? Ideally those exercises can actually show an applicant’s Python skills without asking for an unreasonable amount of work, but I don’t want to be, you know, too optimistic.
  40. We have about a decade left to make meaningful progress on climate change. Are there any projects out there that require Pythonic assistance? Talk us through the onboarding process and then maybe set up a sprint on that project.
  41. I continue to maintain that not enough programmers are terrified by the words “intercalary periods.” Time zones aren’t anywhere near the only difficulties in implementing time into code worthy of a talk.
  42. How we got to Python 3: I don’t think I’m the only one who likes a good code archaeology talk, so an overview of how Python has evolved over the past 20 odd years could be awesome.
  43. Python for writers (fiction and otherwise) could be an awesome talk. I could see coming at this topic from a couple of different ways, like dissecting some of the scripts writers have shared on GitHub.
  44. How to improve search in your projects, especially when you’ve scrapped a giant pile of websites, PDFs, or other data and that pile is just sitting there, silently judging you for not already working with it.
  45. I’m sure someone out there is going to be running 2.7 for years to come, so talks about maintaining and using legacy code are great. If you’ve got any particularly well-aged code still in production, tell us about what it takes to keep that code working. (I have literally written a short story about the consequences of running 2.7 for far too long, so I’m obviously thinking about this topic a lot.)
  46. Could someone with experience in anonymizing data sit us all down and talk about how to anonymize data and what potential issues we need to look out for?
  47. Okay, I’m pretty sure that most conferences don’t want talks about gambling, but I did read an interesting paper about predictive modeling for horse racing and there’s definitely a talk in there. Maybe stay away from talking about betting and focus on the math and horses.
  48. How to triage and understand Python code bases someone else wrote. Honestly, I could probably use some advice about understanding the code Past Me wrote, too.
  49. How to do due diligence on an open source project before using it: There are definitely security factors we need to think about, but we also need to talk more about project sustainability and deciding if it’s worth supporting projects with questionable approaches to inclusion.
  50. While a lot of us use GitHub, there are other version control apps out there (including other git-based options). When does it make sense to use other options for Python projects and is it important to reduce reliance on a single app?
  51. Python in a hurry: what tools and techniques can help get something / anything into production? But you’ll also want to cover the tradeoffs and technical debt accrued along the way.
  52. There are some serious pros and cons to doing genetic testing through 23andme and similar tools, so maybe it’s time to talk about how to do our own analysis of our genetic history (including using some of the Python tools that already exist in this area).
  53. I know NASA uses Python and I just want to say that I am here for *any* talk about using Python to launch stuff into space. (Non-NASA space talks are also super cool.)
  54. What’s the life cycle of a Python library? What should we know before we decide to create new libraries? (Bonus points if your slide deck illustrates concepts using the life cycle of a python!)
  55. Benchmarking the different hosting options for Python-based projects would make a great poster session topic (and I would probably ask for a copy of that poster for my office).
  56. A lot of programmers learn multiple languages, so where should a Python programmer start with other languages? I know a lot of folks say JavaScript, but I bet there’s a lot more to the discussion.
  57. Software testing on a shoestring budget would be great. There have been a lot of “Python for activism!” talks lately, but one of the results have been some projects thrown over the wall without any testing, because testing seems hard and expensive.
  58. Another technology archeology idea: what old hardware can you get running with a more modernish interface? And let’s go old-school: if you have access to, say, a Jacquard loom, what can you do with it with a modern programming language?
  59. Building local mapping systems, especially in ways where data can be shared. As a for instance, being able to map warming shelters (especially the informal ones, like churches) as they open and close in real time would be so useful during freezing temperatures.
  60. Anyone with a generative art project should write it up, in my opinion. First, because all conferences need more art. Second, because there is some AMAZING art coming out of human / tech combos right now.
  61. Augmented reality is a thing right now. There are amazing museum installations (more art!), accessibility upgrades, etc. out there that we’re not seeing a lot of in talks yet. (I’ve seen several “I made an app for other techbros!” talks, so anything else really would be nice.)
  62. One take on the standard “make your API actually useable” talk I’d love to watch: how to prep your API to work with platforms like IFTTT or Zapier. What does it entail behind the scenes and how many different ways do users find to break things?
  63. Building Python tools for non-programmers would be a useful talk. I’ve seen a couple of great PyQt walkthroughs, for instance, that could really be followed up with another talk on how people actually use GUIs after they’re built, necessary upgrades, unexpected edge cases etc.
  64. Oooh, someone could totally do a talk on code review best practices, especially around what parts can be automated and what bits a human needs to do. If you’ve got some ideas for adding empathy to code reviews (especially for the bits that are automated), that would be great!
  65. There’s some really interesting technology built around religious needs (often with Python). For instance, some Orthodox Jewish business owners take down their websites for the length of the Sabbath. Kosher technology is fascinating and talk-worthy.
  66. I’m so here for data spelunking talks, especially from data journalists. Had to go to absurd lengths with a FOIA request, munge together data sets from old scans, or otherwise work with dubious data? What’s your workflow?
  67. Would someone please give a talk with “How to Teach Your Daughter to Code” as the first slide and “Exactly the way you’d teach your other children to code” as the second? You could follow it up with an actual talk or submit it as a lightning talk.
  68. I’m not sure what the oldest Python code still in use is, but if anyone’s running software using, say, Python 2.0, what does it take to keep that kind of well-aged software up? Even better if you didn’t write the code initially and had to read the previous programmer’s mind.
  69. There are tons of talks on building tools to track and improve health, but very few on tracking and improving mental health. I don’t believe for a minute that none of y’all are tracking mental health data on yourselves, so put in a talk if you’re comfortable talking about it.
  70. If anyone is hardening systems using Python to prepare for natural disasters (or man-made disasters, as the case may be), that’s definitely a thing you should put in a talk on.
  71. I’m always in favor of community-specific trainings about how to work with the community’s code of conduct. Ally and bystander training around PyCon’s Code of Conduct would be particularly nice.
  72. Python has impacted how a bunch of other programming languages have evolved. A talk on those impacts in other languages, along with an exploration of anything those languages have improved upon would be super interesting.
  73. There are entire series of books dedicated to using what you know about one programming language to learn another. What about a talk that uses the same approach to introduce a couple of Python frameworks? What do they have in common? How do they work differently?
  74. How about an intro to building linters? Maybe some best practices, tips on making linters more accessible, that sort of thing?
  75. An annotated discussion of all the Monty Python jokes in the Python language, especially for everyone who did not grow up with the antics of said comedians.

So you have 75 ideas to get you started and roughly a month to write your proposal. What are you waiting for?

A Hanukkah zine update, in time for Hanukkah

A couple of years ago, I made a collection of zines for Hanukkah as a way to talk about what the holiday commemorates and how it fits into the American winter holiday season. Those zines are available on Gumroad (embedded below the post) as printable files for whatever price you’re able to pay.

Miranda Sullivan, New Voices’ columnist covering Jewish zines, wrote a kind review of my zines: Start Preparing Early for An Anti-Nationalist Hanukkah: A Zine Review. Here’s a snippet from Miranda’s review:

For the most part, Bram presents a collection that prompts the reader to create their own modern commentary rather than presenting a monolithic view of the holiday. After reading these zines, to me it’s clear that Hanukkah is being used by today’s American politicians to punch a hole in their “I’m not discriminatory I have (fill in the blank) friends!” card. It also made me think about the close relationship between Zionist settler-colonialism and the United States’ military industrial complex.

Miranda Sullivan

Having this review in New Voices means a lot to me, because one of the first pieces I ever wrote about my Jewish experiences was for New Voices. The publication is written by college students and way back in the day, when I was still in college, I wrote an article about Jewish life at the University of Tulsa.

That article doesn’t appear on the New Voices website these days (which is for the best; I have both progressed as a writer and in my ability to think critically about religion and education). If you really want to see how much my writing has improved, I suppose you can look at this copy on the Wayback Machine.

Honestly, though, you’d be better off checking out Miranda’s other columns on Jewish zines, especially the review of The Jewish American Princess Zine, which dives deep into the racial politics of the Jewish American Princess stereotype.

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)

Charter Overview

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:

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.

Our Python, available for a donation to PyLadies

Text surrounded by green squares following one red square (like a low-res Snake game), reading: "Our Python" Support PyLadies and get an anthology of creative Python works from @glasnt, @oboechick_, and @thursdayb! Make a donation to the PSF earmarked for PyLadies then forward your receipt to pythonofourown@gmail.com

I’m so pleased to announce that the Python fan anthology Nic James and I have been working on is now available!

To get a copy, make a donation to the PSF earmarked for PyLadies here and then forward your donation receipt to pythonofourown [at] gmail.com. You’ll receive a copy of the anthology as a PDF.

Even a small donation counts!

If you’re having a hard time deciding on an amount, here’s a suggestion: If you usually buy tickets to the PyLadies Auction at PyCon, give $5 to 10. If you buy raffle tickets at the Auction, give $10 to 20. If you call your manager and negotiate to buy a painting of Guido van Rossum, you could give $1,000.

My contribution to the anthology is a short story about the long-term impact of sunsetting Python 2. The anthology also includes other contributions: Nic James turned PyLadies logos into cross stitch patterns so everyone can make their own PyLadies textiles and Katie McLaughlin gave us a tour of a ‘completely different’ Cheese Shop.

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.

Writing about Python (even when you hate writing)

During PyCon, I gave a tutorial on writing about Python. I’ve included my script below. You can also watch the full talk on YouTube, but be aware that it’s over 3 hours long if you don’t skip the exercises.

In this workshop, we’re going to learn how to effectively write ABOUT Python. We’re going to be talking about some general mechanics of writing about technical topics, as well as some Python-specific topics.

  • Major pitfalls in Python communication
  • Common Python audiences
  • Strategies for editing and testing content about Python
  • Writing opportunities in the Python community

We’re going to do several exercises to practice these strategies, although they may be a little different than the average workshop exercise at PyCon. We’re going to write prose, not code, so this may be a little different for some of you.

I’d also like to note some specific topics I’m going to cover that can be uncomfortable for some audiences. We’re going to discuss race, gender, ability, and age, along with ways Python community members have been marginalized.

Python Versus Prose

The Python community, as a whole, talks more about communication than many of our counterparts. My personal theory is that Python enjoys a special status in newsrooms. Part of that is Python’s use in data journalism. But I think Django’s development is the big factor: one of the most widely used Python framework came out of a daily paper. 

Python, as a result, is pretty good about documentation. We’ve got decades of good examples to build from, as well as some tools that help us with writing prose as much as they help with writing code.

However, writing code in Python remains a different process than writing prose about Python. One of the biggest differences is in the needs of the audiences for each. The primary audience for Python code is the Python interpreter. Python is a format intended to be readable by machines. We talk about the readability of our code a lot in the Python community — more so than many other programming communities — because we value being able to understand our own code without mechanical intervention. 

We value human-readable code because we, as humans, are responsible for creating and maintaining our code. Our future selves thank us for clear and understandable code: my future self is always happier when my past self makes future maintenance easier. But humans are still a secondary audience for Python code. Beyond an interpreter or a compiler, most human readers of any such code will have at least a passing familiarity with Python. Yes, non-programmers will see the code, but most of the people interacting with it will have a more technical background than the average reader. 

Python’s Pitfalls

Over the course of working on  The Python Style Supplement, I conducted both surveys and interviews about what books, blogs, and other materials members of the Python community read to learn more about the programming language. I also took the opportunity to talk to these folks about what problems they had with Python media — what issues made learning and using Python harder.

There are four issues that I heard and saw over and over again. 

  • I’ll be going through a tutorial and it won’t work, because I’m running Python 3 and the tutorial writer used Python 2.7
  • The writer basically told me to go read the code
  • I keep trying to look up the difference between things like PyPy, PyPi, and PyPA 
  • I can’t find anything written about a particular Python project

As writers, we want to avoid these pitfalls.

I’ve rewritten the four pitfalls here so that we can more easily talk about them from a writer’s perspective, instead of a reader’s.

  • Telling  readers which versions of Python and other dependencies you’re using
  • Creating context for code. Even sample code isn’t self-documenting
  • Explaining and disambiguating the jargon that’s accumulated around Python
  • Getting resources to promote new writing, especially on open source projects.

We’re going to get much deeper into these pitfalls and how to avoid them over the next few hours.

I’m also going to add one more pitfall, based on my experiences writing about Python. 

  • Setting expectations about what Python programmers know at different points in their careers

These are in no particular order, and I’m actually going to start with that last point.

Python Audience

When we’re planning what to write, we need to know who we are writing for. The Python community is not just one giant homogenous whole: even if we limit ourselves to talking about just Python skill levels, we’re still talking about a range starting with folks copy-and-pasting Python scripts without a clue of what they’re doing all the way through to folks who have advanced degrees in computer science.

Writing something useful to every Python programmer on that spectrum is hard — and rare. I’m a professional and I don’t bother most of the time. Instead, I write for smaller sections of that spectrums, sometimes rewriting the same material in different ways to make versions useful different audiences.

Talking about these differences in the abstract is hard. Let’s look at this in a more concrete way.

Python Personas

Here are a few different personas we can find in the Python community. These people are entirely made up, but we can talk about how they would respond to different types of writing.

  • Pat the Newer Python Dev
  • Piper the Experienced Python Dev 
  • Nat the Nonprogrammer
  • Ruby the Experienced-in-Another-Language Dev
  • Darby the Decision Maker

There are, of course, plenty of other personas we could talk about, but this narrows down the field to a couple of key points. I actually use these personas in writing projects and have gotten to know these folks really well. 

All of my imaginary friends here have back stories.

  • Pat is a recent programming bootcamp grad. They’re on the younger side. Pat loves Game of Thrones and will get every reference to that show you can squeeze into an article, but Pat can’t tell you the difference between Monty Python and the Mickey Mouse Club.
  • Ruby got started programming when COBOL was the hot new thing and hates all programming languages equally. Ruby reads XKCD and probably knows more about Python’s Easter eggs than Python itself. That’s going to change next weekend when Ruby is going to learn enough Python to pass a programming interview.
  • Darby gets to decide on whether to use Python to build new projects for their startup. Darby often has money to spend and has titles like VP of Engineering and CTO on their resume. Darby also loves football — but not American football. Darby doesn’t use the word ‘soccer’ because Darby works with team members all over the world and doesn’t want to confuse them.

I’m deliberately fuzzy about the race and gender of these personas. Personas aren’t a good tool for figuring out how to address gender, race, and other facets of identity. These personas are MY imaginary friends and they’re a product of MY experience. The furthest outside of my own experience I can go is letting Pat be a Game of Thrones fan, even though I’ve only seen a few episodes. Personas are most valuable when looking at work and educational experience. We will be covering strategies to ensure your writing is inclusive later on. 

In the meanwhile, though, let’s talk about some characteristics we can assign to our personas.

Python Community Members

The Python Software Foundation’s survey of Python programmers is one of the best sources of information for personas. For instance, the 2018 survey found that 50 percent of Python programmers also use JavaScript. 

I’m super confident that Piper, our experienced Python developer, is going to be familiar with JavaScript. Even if Piper doesn’t use JavaScript every day, we can assume a basic level of knowledge.

Pat, our newer programmer, might have JavaScript knowledge, but we’re going to want to add extra context and maybe even link to some resources. As it happens, Pat’s bootcamp curriculum was very thorough — but Pat still wants to know why Java has its own scripting language because even the most thorough curriculum is going to have to gloss over naming decisions made when Pat hadn’t yet started kindergarten.

We can make similar assumptions about Piper and Pat’s familiarity with popular frameworks and libraries in the same way. 

These assumptions are as good as the data they’re based on. The PSF’s survey is based on self-reporting, so there are probably some folks it misses. But it’s still significantly better than other surveys of developers because the PSF works hard to get respondents from different backgrounds. In contrast, surveys of insular communities don’t give us particularly useful data. If you rely on Stack Overflow’s developer survey, you’d be working off of the assumption that 11 percent of programmers are women. There’s a gender disparity in programming for sure, but most programming communities are looking at closer to 24 percent women, based off of surveys conducted by Accenture in 2016.

Python’s Continuing Growth

Overall, the Python community continues to grow. Its expansion means we need to talk about what that growth means for our personas in the long run.

Our community is trending younger, which is great for the longevity of the Python programming language. But that also means that we’re getting more community members who associate Monty Python with their grandparents. 

Our community is also trending more global, including programmers whose first language is not English. Only a fraction of Python writing happens in languages other than English and translations are not as common as anyone would like. 

Both of these trends impact how we can write about Python. As more people use Python, we can’t assume everyone will have access to the same media or will get the same jokes. We need to think about the context these readers need, whether it’s an Easter egg explainer or an explanation of why a certain decision was made. 

Humor is tricky when writing about technical topics. Jokes tend to need a lot of context. Even puns require knowledge about pronunciation. Jokes can also age your content faster than technical issues. One additional note about humor: think about who you are making fun of. Punching up is funny. I feel comfortable snarking about Monty Python because the members of that comedy troupe have made serious bank and have legions of fans ready to talk about the good points of their careers. Punching down is boring. If I want to watch someone make jokes at other people’s expenses or use humor to be a bully, I can just watch the news. 

Monty Python’s 50th Anniversary

I’ve mentioned Monty Python in this talk a few times so far and we need to talk about it. When Guido van Rossum named the Python programming language, he was referring to Monty Python, not a snake.

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

I’m making sure to describe exactly what Monty Python is, because we can’t assume that everyone using the Python programming language also is culturally fluent in Monty Python. That’s because Monty Python turns 50 next year. We might as well be asking programmers to get references to The Beverly Hillbillies, Petticoat Junction, or Green Acres. That in itself isn’t necessarily a problem, but some jokes age better than others. Monty Python isn’t aging particularly well. 

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

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

Styles in Python

Within the Python programming community, we’ve established standard styles for code, as well as naming schemas, both formally and informally. 

We have PEP 8, the style guide for Python code, which includes naming conventions for variables, method names, and such. It doesn’t specifically include suggestions for how to write prose, though some of its instructions are just as useful for prose as for code. PEP 8 prioritizes for readability and consistency in code. We can take those instructions to heart when writing.

We also have less formal systems, especially for project names. For instance, many Python conferences and user groups include the city they’re located in their organizational names. Geography is a relatively easy way to disambiguate different local communities from larger overarching communities. We can tell that PyLadies Atlanta and PyLadies Santo Domingo are two separate groups. It gets even easier because there are unique identifiers for different locations in the form of IATA codes. IATA makes sure airport codes are unique, since there are very important differences between Portland, Oregon and Portland, Maine, if only because my home is in Portland, Oregon. IATA’s codes are so convenient that sometimes cities use them as nicknames or identifiers. Not all cities’ IATA codes are exactly intuitive. Chicago airports, you better believe I’m looking at you right now. Those sorts of departures from style — these inconsistencies, if you will — often require explanations so that readers don’t get distracted from a tutorial by trying to figure out where the writer is from.

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

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

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

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

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

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

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

Name collisions are our future, by the way. Unique identifiers are hard and we keeping building new things we have to name.  We need to get used to disambiguating between similarly named tools in our writing as a matter of course.

Disambiguation

Disambiguation is a fancy word which just means clarifying what you mean by a particular word — or name. If, for instance, I’m talking about Python, I’ll say Python, the programming language, not the snake. Just like spelling out abbreviations, you only need to disambiguate terms once in a piece of writing. You can even do it in a footnote if you’re the sort of person who likes footnotes. 

When writing about a programming language with multiple versions, disambiguation becomes even more important. No one enjoys getting halfway through a tutorial before realizing they’re using the wrong version of Python or some dependency. There’s a really, really, really easy solution to this problem, though: NOTE THE VERSION OF PYTHON YOU’RE USING WHENEVER YOU WRITE ABOUT PYTHON. Even if you assume everyone you know is on Python 3, include the version number. Python 4 is mostly a glimmer in people’s eyes, but folks are starting to talk about what might be included when that version comes around. Similarly, there are not only people still using Python 2.7, but even earlier versions. If you only remember one thing from this workshop, please remember to include version numbers. 

While some writers like using links for disambiguation, I’m not the biggest fan. I strongly encourage you to keep your disambiguation, and other necessary context, in your writing, rather than sending readers off with links. There are several reasons.

The first is that I’ve spent a lot of time writing content with marketing in mind. Whether you’re trying to sell a product or win over a new user, you never want to give up a reader’s attention. If you send a reader away, you may not get them back.

The second reason is that not everyone will be able to click links. Most of us are probably used to high-speed internet where we can access everything we need and download every package we see. The only time we really worry about downloading anything in advance is for workshops like this because conference wifi doesn’t always perform well.

But not all of your readers have that experience. I know a Python instructor living in Alaska who relies on satellite internet. When he travels outside of his home town, he downloads packages, updates, books — any large files he needs — because downloading these files at home is next to impossible. In the state of Alaska, around 15 percent of households can’t access internet faster than 10 megabits per second. You can technically watch Netflix with 10 megabits per second, but you’re not going to enjoy it. 

Lastly, even if your readers have high-speed internet, links can break. Even if you’re maintaining and updating the content you write, preventing link rot is tough. 

I’m also not the biggest fan of relying on search to provide context for similar reasons. Expecting readers to google topics doesn’t always end well… I’ve heard of readers winding up on Urban Dictionary pages, learning extremely non-professional definitions.

Clarity

When you’re writing about Python, you have one goal: writing as clearly as possible. While disambiguation is a major pitfall when writing about Python, it’s only one part of clarity. Whether you’re writing support documentation or tutorials, you need some other human to be able to apply those concepts after reading them. That means writing the clearest prose possible (and, if you’re anything like me, some ruthless editing to get rid of any fancy writing that creeps in along the way). Given our diverse audience, there are several tactics for ensuring clarity.

  • Choose a tone before you start. As a community, Python is fairly informal. There’s kind of a spectrum to formality, though. While informal tones are great for talks, when you need to relate with other people in the room, they’re less useful in documentation, where a personal tone can distract from key content.
  • Keep your sentences short. Especially if you’re sharing instructions, you want a clear and short statement containing one step (or concept). Short instructions are easier to follow, as well as to test.
  • Keep your tenses consistent. Check your verbs to make sure they all follow the same patterns — no jumping between the past, present, and future.
  • Keep adverbs and adjectives to a minimum. Along with bulking up sentences, too many descriptive words may distract readers from your content.
  • Explain antecedents — Keep your pronouns and the nouns they refer to clear. Those nouns that pronouns refer to are called antecedents and you never want them out wandering on their own. 
  • Limit passive sentences. They’re often the longest sentences in a given piece of writing, they often rely on unclear pronouns, and they flop around waiting to trip up a reader. If you’re struggling to identify passive voices try adding the words “by zombies” to the sentence. For instance, consider this sentence: “The program was written to automate work flows.” I can add “by zombies” to the end and it still works. “The program was written to automate workflows by zombies” is a clunky sentence but it works. That means the sentence is passive voice and worth changing to something like “I wrote the program to automate workflows.” In comparison, “I wrote the program to automate workflows by zombies” makes no sense.
  • Be confident in your writing. Avoid phrases like “I think”, “probably”, or “most likely” as much as possible. This sort of wishy-washy language just gives readers doubts.

Clarity can kinda be measured. You may see suggestions that your documentation and other materials about technical topics should be written with an 8th-grade reading level in mind. Basing your reading levels on some abstract idea of what an 8th grader in the U.S. may be able to read may not provide useful context, but there are various tools (including built-in metrics for some word processors) that smush together data. If your only metric is graded reading levels, you’ll want to write to what your tool considers an 8th grade reading level. These tools are automated, though, and not exactly accurate.

For what it’s worth, this talk is closer to a tenth-grade reading level, because I use words like ‘disambiguation’ and ‘antecedent.’ Technical terms or jargon are usually considered more advanced, without a lot of consideration for whether you explain or contextualize those terms. Consider reading levels a rough guide.

Findability

Findability is just as important as clarity. No matter your use case, people have to be able to find your writing to be able to use it. 

The question of findability overlaps some with disambiguation. We don’t want people researching ancient mystic oracle snakes when they search for Python, after all. And if you want to nerd out with me about the use of oracle snakes in ancient Greek, please see me after.

For some people, findability is roughly equivalent to search engine optimization, or SEO. With SEO techniques, you’re telling search engines how to find your material. Search engines are important, but since our actual readers are humans, we need to go further.

  • Use brand names correctly. Python, Django, AWS, and other brand names are recognizable. Making clever jokes or creating your own abbreviations for brand names almost always adds confusion. 
  • Include error messages. Whether you’re writing about how to fix one specific problem or discussing how to trouble shoot several issues, include the error messages users may see along the way. People routinely google error messages in order to find solutions, which makes error messages useful for SEO. Error messages also let readers know right away if they’re looking at material that can help them with their specific problem.
  • Make your content skimmable. We also want to think about findability within each piece. Humans rarely read a whole document — we tend to want just the information we’re looking for. That used to mean looking at the table of contents and index, but indexes are far less useful for a digital document. When writing for screens, making your content skimmable and searchable is key. If you’re focused on writing clearly, especially in choosing words that will make sense to your audience, you’ll also be writing for findability. To make your writing more skimmable, you’ll want lots of headers and whitespace. If you’ve been coding in Python, you may already be excited about both whitespace and clear labels.
  • Differentiate code samples. While Python code tends to be pretty readable, most folks will need a visual cue that they’re reading code, rather than prose. That differentiation doesn’t have to be extreme — just setting code samples in a monospace font, rather than the font the rest of your writing is in, gets the job done.

Once people find your writing, you also need to convince them that you’re trustworthy.

Trustworthiness

Not all writers are trustworthy. I’m not saying that we’re a bunch of scammers, but rather that a lot of writers fail to earn the trust of readers. 

  • Respect the reader. Patronizing or talking down to readers is a surefire way to lose those readers. 
  • Respect the community. The Python community can feel huge, but it’s really quite tiny when we consider how interconnected it is. None of us know every other single Python user, but I’ll guarantee that most of us are familiar with the same authors, as well as leaders in different areas of the Python ecosystem.
  • Be informal (relatively speaking). Companies may need more formal tones, at least in copy, but being able to put a name and a face to a company can be really helpful. I can’t tell you how many software consultancy websites don’t have a single person mentioned by name anywhere on the site. A little personalization can help convince a reader that you know what you’re writing about. If you’re comfortable including a photo of yourself, do that too — you want readers to know that there’s an actual human expert behind your content. 
  • Be consistent. Refer to technologies in a consistent fashion — even if it’s not the style other people use. Inconsistencies, even as small as writing PyLadies with a camelcase L versus writing Pyladies with only the first letter capitalized, can distract readers and make them wonder about the quality of the material they’re reading.
  • Make time for updating old content. Documentation rot is a thing, and once that sort of rot sets in, readers will be reluctant to continue using affected materials.
  • Include images, if you have any. I can send you a ton of studies that humans connect faster with visuals than the written word. But don’t just put a photo of a pair of hands on a keyboard. I invented that. In 2004.
  • Write inclusively. I’ve given a whole other workshop about writing inclusively about tech, but the TL;DR is that we have a responsibility to write material that doesn’t make readers feel unwelcome, whether through racist microaggressions, gender assumptions, or even the ability to access material in the first place.
  • Avoid obsolete terms. Technology moves fast and outdated material just isn’t trustworthy. This goes beyond technical updates, though. The Python community has mostly rejected terminology like “master / slave.” I don’t want to rehash the whole argument here, but there are two points I want to highlight: whether or not you feel comfortable using terminology like this, there are people who experience pain when they have to use terms that remind them of terrible experiences. Furthermore, slavery still exists today and diluting the meaning of the word “slave” makes it harder to work against the end of such practices. Second, language changes, constantly, and we should expect more changes. 

Consider 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.) Instead, think about how you can stay up to date on how language is being used in the Python community by reading widely within the community and how to update your past writing when changes occur, even if you’re just going with “find and replace”.

The Checklist

I’ve just thrown a ton of information at you. I know from experience that it’s impossible to keep all of these considerations in mind when writing. But, luckily, we live in the future, so we don’t have to memorize this sort of stuff. Instead, we’re going to use a checklist.

When I’m writing and editing, I have checklists that I run through. I write an outline, then I check the list to see if I’m missing something. I write an incredibly bad first draft, then I check the list. I edit that draft into something useful, then I check the list. Why do I check it over and over again? Because I’ve edited out something absolutely necessary more than once and needed to go back and read that material. Checklists help me catch potential issues before they turn into real problems.

  • Python version number (and version numbers for dependencies, if appropriate).
  • Roughly an 8th-grade reading level (or another metric)
  • Up-to-date tech references (and if you ever work on a project for more than a couple of months, don’t be surprised if you need to go through and update these references more than once)
  • Get rid of passive zombies and unattended antecedents
  • Consistent style, especially when referring to brand names and sharing code samples
  • Eliminate huge blocks of text 
  • Find visuals, if possible.
  • No wishy-washy language. Be confident in your knowledge.

Self-Editing

Some of the errors we caught probably would have been caught by an editor. Many of us don’t have editors, though: unless you’re working in a company with money to market their product, you’re likely responsible for editing your own work or relying on other volunteers in an open source project. 

Self-editing is not enough, no matter how often we have to pretend that self-editing can catch every problem. So what do we do when we don’t have money to pay editors?

Get readers. If you’ve ever written or read fan-fiction — and I’m totally not calling you out either way — you may have heard of the concept of a beta reader. Beta readers go through a draft and tell you where they don’t understand something or struggle with an idea. While most of us aren’t writing Python fan-fiction, the same idea works.

You probably can’t ask one person to read everything you write and give you feedback. Even romantic partners need a break from reading your material. You want to build a list of readers you trust and who are likely to catch things you can’t. Your readers should also be folks who have the privilege of doing this work for free — not everyone can, and asking someone to take on work they can’t afford to do is not okay.

Your list of readers shouldn’t just include technical experts who can proofread Python as well as prose. You’re going to want to recruit readers in several categories.

  • Diversity + sensitivity readers. Sensitivity readers grew out of a practice in fiction writing where writers get specific feedback when writing about people or cultures outside of their own experience. But sensitivity readers aren’t just for fiction! They’re really useful for getting feedback on issues you don’t even know exist. For instance, until I worked with an editor of color, I hadn’t really noticed how often we code “black” as “bad”, such as “blacklist” or “black hat.” Those details may seem small, but they can be hugely impactful on how society as a whole sees Black populations. 
  • Accessibility + test readers. There are so many mechanics that go along with publishing information that can prevent readers from using that information. We’ve already talked a little about how slow internet connections can make our writing inaccessible, but there are many different layers of accessibility. I just finished a project where I needed to ensure that readers with visual disabilities could fully access all materials. In print, that meant using larger type and specialized typefaces. In digital formats, that means making sure your material can be accessed by screen readers and other tools. Asking readers to test your work on multiple devices and platforms is one of the only ways to check your accessibility; while there are standards, a surprising number of websites and publishing tools don’t meet them.
  • Usability + technical readers. Having someone with equal or greater Python experience review your work for technical accuracy is always a good idea. But consider bringing in a reader who is less experienced as well. I’ve even brought in nonprogrammers to read programming materials because they can spot some errors more effectively because they don’t have any implicit knowledge about the topic. A person with a little distance from the project can also help you catch jokes that are hilarious to you but rely on insider knowledge. Sometimes those sorts of in-jokes confuse or exclude people, making it even harder to get up to speed with a new library.  Feel free to ask your family to read over your writing, provided that they’re good at giving feedback. You can never guess who will run into what information and interact with it online. You certainly can’t control who learns about given technical topics — if you could, every member of my family would be banned from ever seeing the word “Bitcoin”. Your family members count as one person in this case, by the way. You can probably assume that your family’s background is close enough to your own that you’ll want to make sure to get some other opinions. Stakeholders. Even when we’re writing outside of commercial settings, we typically know other stakeholders in a project. Depending on what kind of project you’re working on, your stakeholders could include employers and their lawyers, project contributors, and all of your friends who listen to you talk about this project incessantly. That last group should be allowed to opt out.
  • Editors. Lastly, if you can, find the money to pay a professional editor, especially on big projects. It may cost less than you think — and it almost certainly costs less than making a mistake. A lot of editors aren’t in a financial position to contribute to open source for free, so money remains the best way to get them involved.

Persuading folks to work on unpaid projects is never easy. I’ve had some luck creating a sort of editing round robin for certain types of projects — like a group who all look over each other’s resumes and give feedback. 

Whether you’re self-editing or working with other people, give yourself time between passes on your work. Even a day or two can make an article feel fresh. Read suggestions and edits before implementing them, as well. Taking criticism can be tough and giving yourself time to feel your feelings before trying to fix your writing will result in better changes.

Editing Tools

The best editing tools are those that have been in use for a while. Most of the bugs have been worked out of style guides, for instance. Style guides started at newspapers, covering details like how big headlines should be and how to correctly refer to government officials. Designers acquired the idea, creating design style guides with details like exactly what colors are in a company logo and and reusable style elements. Then developers got with the idea and created development style guides, like Python’s very own PEP8. PEP8 covers details like file naming and versioning conventions, along with style suggestions like including whitespace.

In terms of style guides for writers, we have plenty of options. My first love was the AP Stylebook, which is used by a lot of newspapers and other print media. Maybe I’m easily thrilled, but I adore style guides. They’re basically reference guides of just the information you need to work on a particular type of project. I actually make my own style guides just for funsies: not only am I the editor of The Responsible Communication Style Guide, but I also make style guides for basically every project I work on, whether it’s for a blog, a book, or documentation. I write down all the project-specific information, like how each participant’s name is spelled, along with the latest technical jargon, and all the other resources I know someone else will use. 

You may have more than one style guide on your desk when working on a project. In fact, you *should* have more than one style guide. It’s a question of graceful deprecation — you need a project-specific style guide, but having an industry-specific style guide and a more general guide like The AP Stylebook or The Chicago Manual of Style. 

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.

Style guides are routinely updated, by the way. 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.

There are plenty of startups out there who are excited to offer you some sort of cutting-edge automated editing tool. Grammarly and Hemingway are both pretty well-known. These tools are to spell-check as what integrated development environments are to Notepad.

That power doesn’t necessarily equal out to good advice, though. Hemingway, for instance, relies on rules created by Ernest Hemingway. Leaving all his other issues aside, Hemingway was a decent writer — but not everyone writes like Hemingway and Hemingway’s style doesn’t fit all use cases. For instance, Hemingway was opposed to all adverbs and most adjectives. But sometimes we need both adjectives and adverbs to fully explain a process, especially if we need to explain technical jargon. If Hemingway’s rules don’t work for you, that’s okay.

If you’re writing in a language other than English, there may be more effective automated tools. English, however, rummages for spare nouns between seat cushions. It’s a difficult language to analyze for the same reasons that it’s hard to learn: English is secretly a stack of three other languages in a trenchcoat just looking for norms to break.

Some of these tools also have dangerous flaws. Tools like Grammarly work by tracking what you’re typing. That means they’re keyloggers. By default, Grammarly’s browser plugin sees everything. Including passwords. Personally, I really like Grammarly and still use it, but I do so without keeping the browser plugin constantly active. In the short-term, though, expect automated editing tools to continue having quirks and issues.

Writing Tools

While a lot of tooling focuses on the editing side of things, there are a few writing tools that are effective. Templates are hugely helpful.

Just to disambiguate, I’m talking about about written templates: documents with blanks we can fill in like Mad Libs. I’m making a point to specify because I am not talking about templating engines.

There are some tools, like TextExpander, which can be used to fill in pre-existing templates on the go, but a lot of writing templates are just text documents with sections where you can put materials. I create a lot of templates for my work, because I do a lot of work that needs to be consistent. I also really hate staring at blank pages at the beginning of a project. If I have a basic template to fill in, I already have a starting point. For blog posts, for instance, I know I always want to end with a call to action — something that the reader can immediately do, which may or may not benefit me, depending on what I’m writing.

Calls to action are easy to template. My template is just three words: “Do the thing.” I know that I have to give readers a concrete action to follow, with a clear action verb. I’ll add context and detail as appropriate, but I always start writing my calls to action by modifying “do the thing.”

I generally don’t set out to make templates, by the way. Before I write a new project, I rummage through past projects for similar pieces that I can use as a template. Then I make a copy and delete all the bits I don’t need. If I find a particular template useful, I’ll clean it up and save it with the rest of my templates.

There are plenty of writing tools out there. Word processors are, of course, standard. A lot of writing tools are like time management apps, though: people tend to create tools that work perfectly for their specific use case. For someone following similar workflows, such tools can be useful — but if you have a different workflow, such tools can be tough. 

Scrivener, for instance, is a big fan favorite for writing long documents. It’s got a slew of features for keeping track of references, reorganizing chapters, and so on. I can’t use it. My workflow just doesn’t match up, because I look for feedback at multiple steps of my writing process. I’m also all about the brain dump, rather than a strictly outlined approach. In fiction communities, by the way, this debate is often referred to as ‘outlining versus seat-of-your-pantsing,’ meaning that you just start writing and see where you wind up. I do think of myself as more of a pantser.

Writing workflows are intensely personal, so don’t be surprised if the new hotness doesn’t make your writing process any easier. Try out tools, of course, but you’ll probably get more writing done if you’re writing, rather than trying out tools. 

Lightning Talk Submissions

We’re going to try out a template now. This template is for lightning talk proposals. I’ve ran lightning talks submissions at a couple of conferences, as well as given plenty of lightning talks myself. I got over wanting to craft that perfect individual proposal around the time I gave my second lightning talk.

This template covers most of the information you can be asked for when prepping a lightning talk. It’s not entirely universal, but it’s enough to fill out just about every lightning talk submission form I’ve seen. 

Talk proposals have to be persuasive: anyone submitting wants to speak and you need to make sure your proposal stands out. I know that templates can seem like a weird tool in situations where conformity isn’t useful, but once you get into using this particular template, I think you’ll find that a template lets you focus on writing persuasively, rather than trying to make sure you dot every i and cross every t.

So who is the audience for a talk proposal? It’s not the folks who will hopefully be listening to you speak. Rather, it’s the person who approves or rejects talks. Keep that in mind for filling out this template. It’s kind of a secret, but certain details in your proposal aren’t exactly carved in stone if you get accepted.

Let’s go over this really quickly and then we’ll take a few minutes to each write our own proposal.

  • Name + email address. In your own template, you can just add this information and not update it.
  • Short bio. By short, I mean maybe two lines. These two lines need to demonstrate that you’re a great person to give this lightning talk. For instance, if you want to give a lightning talk about Python, your bio might mention what you do with Python.
  • Talk title. I know it’s tempting to be super clever here. I want you to resist the urge, because sometimes the folks deciding on lightning talks skim titles and then decide which proposals to read more deeply. You want something really straightforward and clear, so that your talk gets thr0ugh the initial review process. This, by the way, is one of those details not carved in stone. I routinely will fancy up the title of a a talk when I’m making slides, especially if I can think of something that will appeal to my audience. 
  • Talk description. This is where the magic happens. Because lightning talks are short, this section doesn’t need to be long — but it does need to be interesting. If you have some big reveal in your talk, include it in the proposal. Don’t leave reviewers guessing about whether or not you’ve got something interesting to say. And I promise reviewers almost never give away a good twist ending.
  • The big idea / takeaway: What, exactly, do you want your audience to learn during your talk?

By the way, just following directions and filling out submission forms completely will put you ahead of a surprising number of other potential speakers. 

I’m going to give you a few minutes to fill this out.  If you have an idea for a lightning talk, awesome!

If you don’t have any lightning talk ideas on tap, don’t stress — you can propose a talk about why a new programmer should choose Python over another programming language. We’re talking about the writing here, not the content of that writing. 

Python’s Valuation of Writing

Python and Django both boast amazing documentation free to anyone with an internet connection (and some without). Creating that documentation was perhaps easier because of the availability of a cohort of programmers and documentation writers trained in communication.

We can’t assume, however, that all Python projects will start at newspapers or other media companies. In order to maintain the high documentation standards in this community, technical writers, programmers, and other Python contributors need communication resources. In order to build and maintain these resources, we need to talk about money.

Writing about Python is work; on the same level as coding the software, designing the interface, or testing its security. In an ideal world, every software development team would include at least one technical writer. While this isn’t an ideal world, the costs of documentation, particularly in Python, may not be insurmountable. 

The Python community’s commitment to open source obviously impacts the finances of anyone choosing to work on Python projects, as well as how Python projects (as well as organizations using Python) can generate revenue. Most projects need at least enough revenue (through donations, sales, or whatever) to cover maintenance costs, relying on contributors to subsidize labor costs by providing their own time for free. But providing labor for free (at least under capitalism) can limit both a project’s growth and contributors’ abilities to meet their own needs.

The result is a set of financial patterns seen throughout the Python community:

  • Offering limited documentation for free, while charging for access to full documentation
  • Offering paid training
  • Offering paid support beyond documentation
  • Writing educational materials for larger publishers
  • Hosting installations of free software

These approaches to raising revenues have met with variable success in the Python world. In particular, charging for access to full documentation is controversial. Open source advocates consider free and accessible documentation a core tenet of any open source project. As Jacob Kaplan-Moss put it, “There’s a particularly pernicious anti-pattern in documentation where tutorials are provided for free but the real documentation is only available for purchase. At best that’s lazy and sloppy; at worst it’s downright evil. Free software needs free documentation. If you’ve got otherwise you should be ashamed of yourself.”

Evil may be a strong word but the reality is that there are plenty of organizations that have figured out how to fund open source work without charging for documentation. For instance, Django’s documentation is available for free, while many community members rely on paid training to pay the bills.

But that’s not necessarily enough to meet the needs of Python’s growing community. No matter what position you find yourself in, I encourage you to advocate paying writers and editors. Whether you can get money out of the marketing budget to pay bloggers, out of technical budgets to pay documentation writers, or out of diversity and inclusion budgets to pay sensitivity editors, every little bit will help us continue to create amazing free materials for the Python community. 

Furthermore, be a good citizen of the Python community, especially when it comes to writing and editing. Support other writers and make sure they get credit for their work. Be empathetic when you see typos — and send a pull request to fix those typos when you can. Don’t ever be a jerk to someone writing documentation for free. Being a jerk about a typo may mean the difference between a documentation contributor staying in the community and leaving.

Writing for Other People

So far we’ve mostly focused on writing and editing on our own. But one of the joys of belonging to a thriving open source community is that we can work with *other people*. Sometimes, we can even get paid writing work! 

But we do need to know how to play nicely with others to access those opportunities. So what opportunities are there to write about Python?

  • Talks: Writing talks to deliver at PyCon and other conferences
  • Documentation: Document software you or other folks have created. Documentation, by the way, is often suggested as a great entry point for new contributors who aren’t confident in their technical skills. That’s a little like having an intern handle social media, in my opinion, but that is an entirely different soap box. While documenting open source projects is usually a labor of love, many companies will happily pay documentation writers, both as employees and on a contract basis.
  • Blogs: You may have your own blog or website, but there are loads of different websites running material about Python. The PSF blog, for instance, welcomes guest posts and hires freelance bloggers. There are also loads of websites looking for both written and video tutorials, which tend to get premium rates when compared to articles.
  • Books: I am not necessarily recommending you write a book, especially if you’re doing it for the money. I’ve written several books and I don’t think I’ve earned enough to cover my time in sales from any of them. That said, if you have a book inside you bursting to get out, there are loads of publishers with Python lines. Maybe see me after if you’re considering putting in a book proposal soon — there are definitely some publishers I would recommend working with over others.

When you’re writing different materials about the same topic, it’s worth noting that you can repurpose material. If all your writing is focused on Python, you may be able to create new work with less of an upfront investment.

For instance, if I was pitching a Python book right now, I’d write somewhere between ten and twenty really in-depth blog posts, and then edit them into more of a book format. You usually can’t use the same material word for word — that’s considered self-plagiarization in a lot of circles — but you can use the same information and the same format to make something new. 

Aside from getting two projects for maybe 1.5 times the work, this approach gives you material to persuade editors and publishers, along with conference content committees, to take you more seriously. If you’ve got published blog posts about a topic, you’re an expert in that topic. You may not be the most knowledgeable expert in the world on that topic, but the research necessary to write a bunch of blog posts is far more research than most people have done. It makes you a known quantity, with proof that you can write about that topic. Most editors and publishers will want to see samples of your writing before committing to a project anyhow, so you might as well make those writing samples do as much work as possible.

A lot of sites that routinely publish freelance or guest writing will have other requirements as well. Luckily, they’ll often share these details so that we can easily review them and submit our writing. These submission guidelines can vary from a few sentences and an email address to a fairly elaborate document laying out not only writing requirements but publication-specific styles. 

OpenSource.com Submission Guidelines

Let’s take a look at the submission guidelines for OpenSource.com. Their guidelines are pretty detailed, which makes them relatively easy to write for. 

  • They tell us the technical details of how they want writers to submit work — where to send articles, which file formats to use, and so on. In general, you don’t ever want to deviate from these instructions.
  • They give us a site-specific style guide so that we can make sure we get tone and formatting correct.
  • They tell us what kind of articles they’re looking for, including how long those articles should be.
  • They tell us some information about our audience, explicitly pointing out that some of the site’s readers are newer to technology. I’d probably use Pat’s persona to figure out how to write this article, because Pat generally matches up with this description. I do think we can assume that Pat has a little bit of Linux experience, even if they aren’t primarily Linux users.
  • They tell us how the material will be licensed. If you’re concerned about reusing material or getting paid for it, pay attention to what rights you’re assigning to a publisher. In this context, a Creative Commons license makes sense. 
  • They also tell us about their backlink policy. Because a lot of folks use guest posting as a way to manage their ranking in search engines, a lot of publishers have become very careful about how they handle links. You’ll see this sort of policy much more often on sites that don’t pay writers, because most people don’t write without getting at least a little something out of it.

I do have to point out that a lot of websites would much rather hear your idea for an article and then help you develop a draft, rather than receive a mostly complete article. Personally, I prefer not submit full articles to sites I’m not already familiar with — OpenSource.com is a known quantity and I trust their editors not to be jerks, but there are editors and publishers out there who will take advantage writers who are willing to write without a confirmed acceptance. 

One of the reasons that we’re looking at OpenSource.com is that one of their editors is attending PyCon and is actively looking for folks to write for the site about Python. OpenSource.com doesn’t pay contributors, but if you can afford to write without pay, it can be a beneficial place to get a byline.

The other reason is because we’re going to write short articles right now, using all the stuff we’ve been talking about.

Let’s Write Something

Exercises that reflect what you’ll experience are always better than something that can only mimic reality. Our last exercise today is going to be writing an article that meets these guidelines from OpenSource.com. I am going to add a couple of additional constraints to make sure we can both practice the skills we’ve covered as well as make enough progress in the time we have left for me to give you personalized feedback.

For this exercise, you’re going to describe a Python library and explain its value. Try to pick a library you’re familiar with because we don’t have a lot of time to devote to research. This sort of article meets the requirements for OpenSource.com’s for 500 to 600-word articles. However, I don’t expect you to write a full 500 words before we wind down this tutorial.

Even if you identify as a pantser and you like to just dive into writing, I’m going to ask you to outline what you’re going to write. They don’t have to be complicated, but they’ll help us discuss what your article might entail if you hit 500 words. Your outline should answer three questions:

  • What’s an example of how this library has been used? We’re talking real world examples here. 
  • What do I need to know to be able to use this library?
  • How is this library better than competing libraries?If you truly can’t find any competition even by googling, you can tell me that instead.

Pat the Newer Dev needs you to answer these questions before they can decide whether learning about this library is worth their effort.

Don’t worry too much about getting spelling and grammar absolutely correct. This is your first draft and I’d normally suggest doing at least a quick editing pass before handing it over to someone else, but we only have so much time. I promise that all of my first drafts are terrible and that I won’t judge you.

Conclusion

Remember how I was talking about reusing and repurposing your material? As it happens, 500 words is about the right length for a 4 or 5 minute lightning talk. Y’all have just written lightning talks (though you might need to tweak language in order to give it as a lightning talk) discussing a specific library. Nice, right?

As we wrap up, I have just a few last things to say. First, writing is one of those skills that you can only build with use. The best way to improve your writing is to write as much as possible. The second best way is to read as much as possible, preferably from a wide variety of sources. The more time you spend with language, the better equipped you’ll be. 

Also, in case I haven’t said this enough times, ALWAYS ALWAYS ALWAYS include version numbers. 

Lastly, I want to point out a couple of great resources on writing:

  • Jacob Kaplan-Moss wrote a blog post series about writing about Python in 2009. The series may be ten years old, but it’s still a good resource. (https://jacobian.org/2009/nov/10/what-to-write/)
  • The Responsible Communication Style Guide and the Python Style Supplement
  • Sin and Syntax by Constance Hale is a book I strongly recommend if you want to learn more about writing prose outside of the context of the Python community
  • Write the Docs has videos online of years worth of talks about writing and they tend to be really good. As you’re looking for ways to level up after this workshop, watching these videos can be really helpful.

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.