The Guest: A Guide To Code Hospitality

The Guest: A Guide To Code Hospitality by Nadia Odunayo

You were living alone in the town of Ruby-on-Rails until you decided to open up your spare room to guests. Now your first visitor has booked in. Her arrival is imminent. How do you prepare? How can you make sure she has a great visit? Let’s explore the art of code hospitality — working on codebases in a way that respects your teammates and provides for their needs. By working hospitably, we can facilitate team productivity and help new members quickly feel at home.

Help us caption & translate this video!
http://amara.org/v/Psik/

GoRuCo 2016

00:00:15.340 Hi everyone! I want to start with two stories. Story number one: a few months ago, I decided to list my spare room on Airbnb. It wasn't long before a woman named Alex booked a stay. Before she arrived, I received a message from her. She said, "I think I want to move to London. I've never been to the UK before, but I'm looking for something different." I replied, "Cool!" Then she asked, "Will you help me, please? If you have any time to show me around London and tell me what it's like living and working there, I'd really appreciate it." Sure, I said. Before she arrived, I tidied up the flat and put together a little welcome pack for her. It included a tourist book, a tube map, and a sheet of tips and tricks for getting around London, like "don't smile at anyone in public" and "always carry an umbrella, even if it looks sunny." On the day she arrived, I went to pick her up from the airport. When we got home, I gave her a tour of the house and the welcome pack. She seemed to really like that. After she rested for a bit, I took her for a quick tour of our area and over the next couple of days, we visited a mixture of popular tourist attractions and some of my favorite quirky spots in the city. At the end of the day, I took her out for a meal and asked her about her first impressions of London. It was very interesting for me because I was born in London and had lived there all my life. It was fascinating to get her perspective. In the end, she decided to come and live in London, so go me!

00:02:02.390 Now, onto story number two. Theo, my business partner, said to me one day, "Rails is my city, and I've lived here all my life." We run a company called Ignition Works, and at the moment, we're working on a system that helps organizations better document and act on their processes. While pairing, I was struggling to grasp a concept that was easy for him, and I found myself anxious and frustrated that he might be disappointed with me. His words made me feel better and put my struggles in perspective. I felt like I was a welcome visitor in his hometown of Ruby on Rails, and I hoped to make this place my home too. I started to think about how I could make the most of this situation and what Theo could do to help me. These reflections reminded me of when Alex came to stay with me. We both wanted her stay to be as pleasant and enjoyable as possible, which is where the concept of "code hospitality" comes from. By setting the scene of a host receiving a guest, we can explore effective strategies to treat and respect new teammates. This is essential for onboarding people efficiently and working together on our codebases, ensuring our environment is both fun and productive.

00:03:18.410 I hope you'll leave this talk with a new way to approach problem-solving, particularly regarding coding and developing new features. Additionally, I want to share a new perspective on communication, emphasizing giving and receiving feedback. With code hospitality, we can improve collaboration and long-term learning across teams everywhere. So, who is this guide for? First, let’s confirm relevance. I will present statements on the screen, and if they relate to you, please raise your hand and keep it raised. If the next statement also applies, raise your second hand. If more than two apply, somehow indicate that but please do not shout out. Let’s make this fun! How many of you have recently started a new job? How many have a new team member? Have you recently rotated onto a new team? Started a new project? Are you using an unfamiliar language? Do your colleagues regularly look to you for direction? You want your team to be productive and happy? If you raised your hand for any of these, you’re in the right place!

00:06:03.580 Let's move on to the introduction. Think of the last time you had a guest. What did you do to make their stay pleasant? Remember your last experience as a guest; perhaps you stayed with someone in New York City. Did you enjoy it? We all have clear ideas about what makes a good host or guest. As a host, you might clean up before their arrival, ensure they are comfortable, or even make them some food. If you think about being a good guest, maybe you bring a gift for your host or offer to help tidy up afterward. This all boils down to hospitality, which refers to the relationship between a guest and a host. At the center of this concept is respect for your guests, providing for their needs, and treating them as equals. Hospitality is ingrained in our society and culture; we know the expectations and roles we should fulfill when hosting guests each day. However, we often do not extend this same quality of care to our workplace interactions.

00:07:10.080 This is primarily because we fail to connect the dots between house hospitality and code hospitality. Sometimes, we neglect those around us and take them for granted. In the office, we ask ourselves the same question as with a guest in our homes: how can we collaborate better when two parties are likely feeling vulnerable and uncertain? As a guest, you might feel vulnerable in an unfamiliar place, unsure of how you will be received. Conversely, as a host, you have someone entering an environment you're accustomed to, but the outcome is still uncertain. This uncertainty can breed discomfort and misunderstandings. To set the tone for effective collaboration, it's crucial to establish the right atmosphere. When I mention the guest-host relationship, I'm not referring to the dynamics of junior and senior levels. It's more about familiarity, which can vary across different domains, including code, company culture, or team dynamics.

00:08:27.680 When considering how to approach problem-solving with others, remember that these relationships can be fluid. I partnered with an experienced iOS developer earlier who was new to testing, and despite my lack of experience with iOS, I was able to host in the sense that I brought testing knowledge to the table. This reflects a mindset shift; it’s a useful thinking framework when approaching problems. Cleaning up is another essential aspect of code hospitality. When you receive someone, do you tidy up beforehand? Imagine showing up to someone’s house — how would it feel if it were a mess? The same applies to codebases: like a house, keeping things tidy makes a world of difference because unexpected guests may show up, and messy code increases upfront complexity and cognitive load.

00:09:47.960 Keeping your codebase organized helps when working on more complex problems. When you clean, what does that mean? Everyone has individual cleaning styles. Theo and I like to ask ourselves whether we have named things consistently to clarify what’s going on, or if our code is readable. After ensuring you've cleaned up and organized your workspace, the next step is showing your guests around. I sent out a tweet asking people how they introduce new team members to their codebases. Many mentioned starting with their tests. For instance, one woman at an insurance company said they begin with the main insurance policy object and branch off from there. The term 'diagram' came up several times. Many people indicated that a bunch of diagrams telling the story of their codebase provides context to newcomers, rather than merely listing objects without narrative.

00:11:26.610 What might compose such a story? It could include code objects, methods, and how they interconnect, but also the broader business concepts at play. For example, a while ago, Theo and I worked on a project with a significant nutrition component. We did extensive research on various diets and their effects on different body types, which helped inform how we allocated responsibilities in our coding tasks. If you can think about how the wider business concepts relate to the code structures, it allows for a more comprehensive narrative for newcomers to understand the history of the codebase. When discussing code hospitality, we need to consider the type of guest arriving. We have a special version of guests called 'open source guests.' These are individuals who come into your codebase when you're not around, much like staying at an Airbnb.

00:12:57.300 Have you ever stayed at someone's home when they were not there? You typically find a letter or guide detailing actions and instructions. If you visited my friend Pete's house, for instance, you'd find instructions on how to feed his dogs. In code, a readme file serves a similar purpose; it consolidates what you've shared with newcomers, ensuring they know what to do when you aren’t available. A well-constructed readme includes system dependencies, setup instructions, and how to run tests. These elements are essential for getting set up, but they don't inherently guide you on progressing or delivering features. So, what more can we do?

00:14:25.450 I explored different readme templates and found an interesting section in the Active Record readme discussing how it serves as an implementation of object-relational mapping. It provides a brief explanation of its operations, links to blog posts, and outlines the high-level implications for how code is developed. A new developer approaching Active Record can get a sense of the entire project context without a maintainer present, with guidelines for seeking additional information. For open-source projects, we must think about crafting readme files that make newcomers feel welcomed. An example could be a hospitality guide app. In addition to installation, usage, and contribution info, it can include historical context, development approaches, and reading materials. This storytelling approach creates a sense of guided exploration within a codebase.

00:15:52.040 Given that you've equipped guests with the required tools, it now becomes vital to establish a conducive atmosphere. Consider the balance between 'giving someone a fish' and 'teaching them to fish.' A conversation with a colleague reminded me of this metaphor. He said, 'Give someone a fish, and you feed them for a day. Teach them to fish, and you feed them for a lifetime.' However, if that person is starving, you may need to give them fish first before efficiently teaching them. This balance needs to be struck when new team members join. Practically speaking, when someone new comes onto your team or joins your codebase, it’s essential to extend generous help to them initially. You want them to rapidly become self-sufficient while acknowledging that this is a safe space for questions, requests, and mistakes.

00:17:16.990 Consider suggesting a lunch-and-learn session about something you know well that others might not. Make it clear that your new guests can ask anything, at any time. Newcomers should also feel empowered to speak up, whether about terms they don’t understand or aspects they’d like to explore. For my first development job at Pivotal, we paired constantly, ensuring I had someone to ask questions without fear. Sadly, I’ve heard many stories where new developers hesitate to approach more experienced teammates for fear of bothering them, especially if they appear engrossed in their tasks. Most often, that experienced person would appreciate questions, but it can be difficult to gauge, highlighting the need for a conducive environment.

00:18:54.520 It's crucial that we encourage new teammates to feel at home quickly. Every effort we put in to welcoming and involving them builds a nurturing environment. When I picked up Alex from the airport, that was my way of making her feel relaxed and setting the tone for her entire visit. With that foundation in place, it’s now time to deliver value. Being productive in coding means building features, and I have a question for those of you who use Rails or any other frameworks regularly: If I asked you to draw a map of Rails right now, what do you think you would create? Would it resemble something specific? Notice how all interpretations will look vastly different, even from those seasoned in Rails. The main point I want to convey through these diagrams is that understanding is subjective; it’s not merely about familiarity with a framework but about individual reasoning and perspectives.

00:20:12.290 When you tackle tasks, consider what might happen if a new team member joins you who knows little about the codebase. For example, let’s say the next feature you're working on is about a user wanting to access the Tower of London. Picture yourself at your desk, envisioning a clear approach, while your new colleague may entirely lack that context. Different perspectives lead to differing solutions. Reflecting on my time with Alex, one day she called me, stating she was outside the supermarket Tesco but didn’t know how to get home. I gave her directions based on the Tesco I always frequented. It turned out she was at a different one altogether, which highlights the importance of understanding each other’s positions. When coding, it’s essential to identify and align such perspectives.

00:22:08.970 Let me share an experience: a few weeks ago, Theo and I faced a coding problem. After writing tests, we needed to implement the code, but our discussions felt stagnant. In the heat of the moment, Theo suggested I draw my understanding of the problem. As soon as I sketched it out, it became evident where our communication faltered. It clarified through diagrams how things interconnected and what messages flowed where. We then utilized a role activity diagram, and everything came together, allowing us to complete the feature swiftly. The moral here is that when collaborating, whether as a host or guest, assume confusion is mutual. If one of you comprehends the situation, it’s critical to recognize that the other person might be lost. Use visual aids like diagrams to facilitate better communication.

00:23:38.800 Questions naturally arise when working together, especially if one party is unfamiliar with the environment and processes. Consider another example with Alex: she asked me for directions to the pharmacy, and since I didn’t have time to take her, I referenced the restaurant we visited earlier as a landmark. However, she didn’t recall how to get there. This interaction underscored my realization that I had time walked her to the restaurant but hadn't guided her through the entire process, leaving her grasping at pieces. To address this, I sat down with her, provided a map, and explained how to get from our house to the restaurant and then to the pharmacy. In doing so, I empowered her decision-making by encouraging her to choose routes based on the information I provided. This principle also applies to software development: it’s crucial to foster a culture of open dialogue where ideas and methodologies are revisited and explored together.

00:24:58.220 When embarking on coding tasks, rather than perpetually reverting to the things that you've always done, collaborate on brainstorming different approaches. Share various ways you’ve tackled coding challenges and discuss their respective pros and cons. Newer developers might struggle to distinguish between one true method and mere habits or preferences of more seasoned colleagues; establishing a collaborative environment to evaluate strategies together can lead to fruitful discussion and innovation. Shifting the focus from implementation details to overarching concepts allows for inclusive decision-making where everyone contributes. This means experienced developers won’t fall into old patterns and will remain open to exploring alternative solutions that could yield improved outcomes.

00:26:15.470 After you've worked on something, having mechanisms to assess its success is crucial since not everything goes according to plan. Addressing this need is essential to smoothing out the processes for future endeavors. The challenge with feedback is that it’s difficult, and feelings can sometimes remain unclear in the workplace. During a previous talk, someone questioned my emphasis on feelings in a work environment, suggesting it was strange. This reaction made me realize that many people perceive themselves as logical beings whose focus ought to be on productivity, viewing discussions of feelings as distractions. However, we cannot escape the fact that emotions affect our professional environment, and it’s necessary to develop frameworks to communicate about these feelings effectively.

00:27:45.370 Recall my dinner with Alex, where she expressed her thoughts on London without pressure. Regular retrospectives are common in team settings, but I believe one-on-one retrospectives are often overlooked, and we need more of them. These are discussions with colleagues you collaborated with during the day. Such conversations should emphasize feelings linked to specific observations, explaining how they influenced you and identifying any needs that arose. This method is powerful for expressing how needs may or may not have been met. For instance, if you were to voice disappointment about a coding process because you wanted greater involvement in driving decisions, it could foster future collaborations. The goal is to ensure feedback loops are rooted in observations of feelings that arise rather than critiques of others’ actions.

00:29:26.240 By embracing the concept of code hospitality, we begin to grasp empathy more meaningfully. It provides us with a groundwork for understanding how colleagues might feel during collaborative efforts. We have all navigated environments where others possess more familiarity—and we can apply that understanding to workplace dynamics. Through the principles of code hospitality, we hope to continue delivering exceptional work without taking our teammates for granted. We must consistently demonstrate respect and overcome challenges that can impede teamwork, focusing on building value sans tension or insecurity. Wrapping up with rather frequently asked questions: Many of you might like to know where to find a copy of the Code Hospitality guide. It’s available for free at this address.

00:30:59.750 What if you want to learn more about effective communication with colleagues? I highly recommend the book Nonviolent Communication by Marshall B. Rosenberg. It advocates transforming our communication from judgment and demands to a method anchored in feelings, needs, and requests. If you want to explore how to hold one-on-one retrospectives, check out this insightful blog post about collaborating with a peer to reflect on work and identify improvement areas. Please use the hashtag #CodeHospitality to engage in discussions about these concepts and contribute your own ideas. A big shoutout to all the incredible individuals who helped me craft this talk. I want to leave you with a final thought: beneath all these principles, vulnerability is crucial. Embracing vulnerability in the workplace allows us to understand our true needs better and enhances our empathy toward others. When we become aware of this shared state of being, we improve our abilities to communicate and troubleshoot effectively with one another.

00:31:55.720 Thank you for joining me today.