A user's guide for the people API

Longtime Pythonista Ned Batchelder gave the first of four keynotes at PyCon's 20th-anniversary edition, PyCon 2023, which was held April 19-27 in Salt Lake City, Utah. In fact, it is still being held at the time of this writing; the sprints continue for four days after the three days of main-conference talks. Batchelder presented his thoughts on communication, how it can often go awry for technical people, and how to make it work better.

PyCon chair Mariatta Wijaya introduced Batchelder by suggesting that she would not be in that role today if he had not encouraged her on the day before she was to give her first Python talk. He simply told her that the talk she had put together was good, which was enough to allow her to put aside thoughts of canceling the talk. She chose him as a keynote speaker because she wanted everyone else in the community to know more about a person who was so influential for her when she was getting started on her Python journey.

Batchelder works for edX on Open edX, which is a large Python and Django application. When he started to think about what he would talk about in his keynote, he considered something from his work, say online education, million-line monoliths, or building a large open-source project in a for-profit company. He also maintains coverage.py and a few other projects, so he could perhaps talk about maintainership topics. Or, since he is one of the organizers of Boston Python, maybe a topic around organizing during the pandemic would be interesting. Beyond that, he has been writing a blog for longer than PyCon has been around; perhaps he could talk about "what it is like to put ill-formed opinions out on the internet for abuse". Instead, he could talk about the experience of helping beginners on IRC, Slack, and Discord—or on the differences between those communication channels.

But he wanted to do something bigger than any of those; "it's a keynote, it should be big". He deadpanned that he decided to talk about "high-uncertainty components in complex systems", which was perhaps not met with the laughter he expected. In any case, that was not the talk topic, though he did want to talk about "things that are less certain to us and how we interact with them". Rather than the "fancy high-tech jargon" he had used to hopefully grab attendees' attention, "the simpler way to describe what I am going to talk about is 'People'".

People

"We as engineers" may tend to try to interact with people "as if they were technical components"; we may think less of the work that needs to be done to interact with people and, as a result, those interactions do not go as well as they could. But we can use the skills that we have for learning how to do complex things and apply those skills to working out how to make our people interactions go better.

These kinds of skills are known as "soft skills", which is a term that some people do not like. For him, the term makes sense; engineers tend to value the "hard edges of the hard skills" because those tasks can be quantified, reasoned about, automated, and tested. Dealing with people, on the other hand, is "all squishy and subjective, there's no linters that you can apply to your Slack conversations or whatever". That's precisely what makes the soft skills so difficult; they are "squishy and soft", which makes the term resonate for him.

"If you think about it, people are terrible", Batchelder said, but that is really only true if you treat them as components. If you take your interactions with people seriously and do a good job with those interactions, people will not be terrible. People are non-standard; they all differ in various ways, large and small. Things you might say to one person may have a completely different effect on another. When you first meet a new person, "there's no documentation" on what to expect or how to interact with them, which makes people, especially new people, unpredictable.

Part of what makes people unpredictable is all of the hidden state that they maintain. Something to avoid in Python programs is mutable global variables, but "people's heads are full of mutable globals". When someone talks to him, he may still be thinking about the horrible breakfast he had or that his shoes are too tight; the person interacting with him has no idea about them, but those things color his responses.

The hidden state sometimes leads to non-linear reactions. A seemingly innocuous statement can lead to a loud, angry response, far outside of the realm of expected reactions. As engineers, we would like (and expect) that a little more input only produces a little more output, but "that is not the way people work".

When things go wrong, you may try to elicit what the problem is, only to be told "nothing", which is "a terrible error message", he said to laughter. We like our systems to give users feedback about what went wrong, but people are sometimes not able to do that. They may not want to talk (or talk with you) about the hidden state that is driving their reaction or they do not feel like they are "allowed" to have the feelings that they have. We need to take these kinds of things into account in order to try to keep things going well.

Even though you might prefer to spend time with a Raspberry Pi rather than try to interact with an unpredictable human, the reality is that you do not really have that choice. No matter how introverted you are, you have a boss, you have coworkers and collaborators, you will have people who use whatever it is you are working on, so you are going to have to deal with people. It is too easy for engineers to just overlook the people aspect of their lives and jobs, thus have things come it out badly. If, instead, you focus on it as a skill that you can learn and build on, "it can get better".

"Let's face it, people are fantastic"; each person can do some things that others cannot. People are flexible and creative. Had Wijaya asked a bunch of computers to help her organize PyCon, it would not be a good conference, but she asked people and "they are flexible and can adapt and do great things".

But, rather than trying to convince attendees that they should want to talk to people, he was going to focus on his overall topic: "how to talk to people". Since it was a technical audience, Batchelder suggested that attendees simply think of it as "People: the API User's Guide". He cautioned that he is an engineer, not a psychologist; his ideas come from spending time "debugging a bunch of interactions, reverse-engineering a lot of people, reading the tracebacks from a lot of discussions that did not go that great and thinking about how they could have gone better".

API

All communication, by voice, email, pull request comment, text message, and so on, has two components. It has the information content, which is what you are trying to tell the other person, such as "don't use xyz() here" or "I need you to do this task", but it also always has sentiment attached; "that's just the way people work". When he talks to someone, that person is thinking about how Batchelder feels about them; it is similar to the "sentiment analysis" that is done to figure out whether people like a sneaker brand based on their tweets. "People do sentiment analysis all the time", even if they are not aware of it.

In the end, every message gets boiled down to either a "yes" or a "no" with the sentiment analysis; the "words in the message can either welcome you in, or they can push you away". Sometimes the effect is tiny, but sometimes it is huge; he believes that every message gets characterized to fall on one side or another of the yes/no divide. "The goal is to try to make every message be a 'yes'."

The problem with this analysis is that people "will find a sentiment, even if you didn't put it in there". They will default the sentiment that they find in a statement based on things like their history with the speaker; based on Wijaya's previous experience with Batchelder, she would probably be inclined to default his communications as a "yes". The same message given to a person with whom he has had a lot of conflict will likely default to "no".

Another factor that comes into play is "similarity"; a PyCon attendee will be more inclined to receive a message as a "yes" from another attendee based on that similarity. If someone has no history and finds no similarity with the sender, the default sentiment is likely to be on the "no" side.

Batchelder cautioned that he is not, by any means, perfect at communication. He has had conflicts with people in the room (including his wife who was sitting in the front row, he said with a chuckle) that went poorly because he was careless and said something without being thoughtful about it, which struck the other person wrong, so that the two of them needed to unravel it later. He knows it will happen again because he is a human. From a programming perspective, the goal is not to never have bugs, "the goal is to be good at recognizing the bugs and fixing the bugs when they happen".

You want to avoid having your messages fall into the "no" category because that will put people on the defensive. He put up some Python code to represent how a message is received, with steps like calls to self.find_history(sender) and self.apply_hidden_state(sentiment). One important thing to note is that once some sentiment gets "calculated", the following call is made:

    self.add_to_history(sender, sentiment)

Engineers often want things to be different; "can't we just stick to the facts?" But the answer to that is "no". "For the time being, at least, we are still talking to people; we are not going to be talking to robots. This is the way people work." The sentiment analysis is a two-way street, of course, because the sender will have their own analysis about the receiver that will influence the message as well.

Improve

There are a number of ways to improve the chances that our communications have better outcomes, Batchelder said. He went through some examples, using an online-chat-like format since that works well on slides. They are structured as a newbie asking a question on, say, Slack or Discord, which make good examples because "they are intense crucibles of this kind of interaction".

The first principle is to "say yes", but he also formulated it as "don't say no". So, when a newbie asks how they get the length of the array "[1, 2, 3]", the right answer is not "that's not an array", no matter how accurate it might be. That answer is "absolutely correct, totally unhelpful"; it even includes the "no" word "not". The newbie has now concluded that they must be stupid. A better, but still accurate, way to say that would be: "The length of that list is len(arr)"; the helper has subtly corrected the newbie without making them feel stupid.

Sometimes, we do not use enough words in our response, which is something that he is guilty of frequently. For example, "I need help with X" should not be met with "why are you using X?" because it sort of implies that they should not be using X, which may well not be the helper's intent. A better way might be something like: "X can be tricky. I had trouble with it when I started using it." Now the person asking will realize that they are not the only one who ran into trouble; even more helpful is following up with something like: "If you tell us more about how you are using X, we can make it work". The information content between the first interaction and the second was exactly the same—but the sentiment was completely different.

"My program says 1+2 is 4"; that program is obviously wrong, that's why the person wants to talk about it, so starting the interaction with "that's wrong" is totally unhelpful. "That's wrong" is closing a door, while "hmm, that doesn't sound right" is the opposite; it opens up the door and the "hmm" adds uncertainty for the person responding, which serves to level the playing field between the two people.

Humility is important as well. The newbie who says "my if loop only returns once" is obviously spouting complete nonsense, but replying with "you aren't being clear" is accusatory. Instead, a response like "I don't understand yet" takes some of the responsibility for understanding on the side of the helper. It is hard for experts to be humble at times because they have worked so hard to acquire all of the knowledge and skills that they have; they are proud of that and certain of some things, but that certainty can close doors. He did not want to get into gender stereotypes in the talk, but he does think that one way to be more humble is "whatever the opposite of mansplaining is, do that"; that was met with a round of applause.

A lot of this stuff is "kindergarten stuff"; all he is really saying is "be nice and think of the other person". He showed a picture of himself at "one-tenth my current age" and said: "that person could have told you this stuff too because he learned it in kindergarten". As we get older we tend to focus on other things, but we are all just people trying to make our way in this chaotic world, he said.

Gutenberg interlude

Batchelder shifted gears to technology, but it was not the technology that attendees probably expected. He has an interest in the history of printing, so he went through some of that briefly; "there's a point at the end, you'll see, stick with me". The etymology of some words and phrases still in use today was one of the interesting parts of the interlude.

Gutenberg developed a process for creating a printed page using movable pieces of metal in the 1400s. Those pieces of metal contained the reverse image of the character to be printed; they were collected up into the page to be printed, ink was applied, and paper was pressed to the collection, resulting in a printed page. That is the origin of the word "press", as applied to newspapers and the like, that we still use today.

One of the challenges was in creating the pieces of metal (the type) with clear representations of the letters needed. Batchelder went through the process of creating them, which eventually results in a mold that can be used to create multiple identical copies of each character using molten metal. An early step is to carve the character onto a chunk of steel, but type creators needed to be able to test their carvings without going through all of the rest of the steps ("even back then it was an ordeal to get your work into production"). So, the "punch cutter" would put the carving into the flame of a candle to coat it with soot, then press that onto a piece of paper to see how it was coming along. That was a "smoke test"; he is aware of other origin stories for that term, but is convinced this one is right.

Once the type was created, a typesetter would stand at a wooden tray filled with these pieces of metal in various compartments; the typesetter would assemble them into lines of type starting from the bottom, "upside down and reading backwards". There were two trays that were always arranged in the same way so that typesetters could move to a different "workstation" as needed. The non-capital letters were in the lower tray and the capital letters were in the upper. "Only they didn't call them trays, they called them cases", so one was the lower case and one was the upper, just as we call them today. "So remember that a case-insensitive regexp is one that does not care whether the chunks of metal come out of the top wooden tray or the bottom wooden tray."

The lower case was organized by letter frequency, so that the most common letters were in larger compartments near the center of the case, while the less-used characters were in smaller bins around the edges. The upper case had the letters arranged "A" through "Z" in bins of the same size—except that "J" and "U" were placed just after "Z".

His intent with the digression was to throw out a lot of information about a technology, much of it likely unfamiliar to attendees, in order to, effectively, turn them into newbies on that subject. He presented the material quickly, with some weird digressions that would perhaps be disconcerting ("do I need to pay attention to that?"); it ended up with a piece of information that is "something so odd that it seems like it must have been done intentionally to annoy us". This is a common problem for newbies.

People wonder why "J" and "U" are placed at the end of the alphabet. "J", at least, is used far more frequently as a capital letter than, say, "X". He wanted to demonstrate that it is not just the sentiment that affects how a message is received; the information in the message can come so far out of left field that it unbalances the receiver to a certain extent.

It turns out that "J" and "U" were both not considered distinct letters in the English language until the mid-1600s. The layout of the upper case had been in use for 200 years, so, "rather than disturb centuries of tradition, they were just added at the end". They remain in that location to this day; if you visit a letterpress, you will find an upper case that is laid out that way. "So the next time you want to whine about your legacy systems and backwards compatibility, go and talk to these guys", Batchelder said to laughter and applause.

Weirdness

Python, too, has its legacy warts. lambda "is a terrible keyword" in his opinion; it has no mnemonic value, since the name does not help people remember what it does. He is not saying that "Python is bad" with that statement; Python is simply technology, which "starts weird and gets weirder" over time. That weirdness can interfere with the ability to communicate with others who are not as well-versed in Python's lore.

He noted that Pythonistas love to show people the xkcd "Python" comic (i.e. import antigravity). On the other hand, "we are not so fond of showing" the "Python Environment" xkcd where the language's packaging woes are aired. He was not putting the latter up to make a point that Python is "bad", it is technology, which "starts weird and gets weirder and that's just the way it is".

We say that Python is easy, and it is, but that does not mean it does not have confusing quirks; "it's still a programming language". Even within the Python community, there are differences. Each type of Python developer has their own sets of terms, acronyms, and so on, which often do not overlap with those of Python developers in other parts of the community. Python web experts may share relatively few terms with their machine-learning or scientific counterparts, for example. We need to keep that in mind when trying to communicate even within our own "little" world.

He had been giving examples from the perspective of a newbie seeking help, but even experts encounter the same kinds of problems. If he started working at Meta tomorrow, he would be a beginner and have lots of the same kinds of interactions, perhaps with longer words and sentences. In Boston Python, they have a saying: "We are all beginners, some of us just have more practice." Experts typically have learned how to deal with being a beginner and now have some skills that help them get past that stage.

It does not help that the world is now made up of a huge number of notifications of various sorts popping up on your computer. Some days when he is working at home, he feels like an air-traffic controller just trying to ensure that the planes do not crash. It is important to remember that those notifications are all, at some level, people; the immediate reaction may be to quickly respond and get on to the next thing, but that flies in the face of some of the suggestions he gave.

"People are important; our interactions with people are important." Beyond what he could present in his talk, there are lots of other things that can factor into our communication, such as group conversations, power dynamics, and how to gracefully stop communicating when things are not going to improve. His advice for the next few days, which echoed Wijaya's opening comments as well as his suggestion in a blog post after his first PyCon: "talk to people". People came to PyCon because they want to talk to others, so take them up on that opportunity.

He closed his keynote with a quote from the writer Mark Vonnegut in response to a question posed by his father, Kurt Vonnegut, who is also a writer: "what are we here for?" The elder Vonnegut was asking an existential question about why humans are here in the world, and the younger "both answered and avoided the question" by responding: "we are here to help each other get through this thing whatever it is". Batchelder concurred with that idea and hoped that attendees would talk with each other, listen to each other, and help each other.

Video for the talk will be available soon, though in-person and virtual attendees can see it on the online PyCon site; we will post a link once it is out. [Update: Video link] Meanwhile, Batchelder has a blog post about this year's PyCon, with some thoughts about his keynote, that is worth reading as well.

[I would like to thank LWN subscribers for supporting my travel to Salt Lake City for PyCon.]