The Guest: A Guide To Code Hospitality

RailsConf 2016

by Nadia Odunayo

The video titled "The Guest: A Guide To Code Hospitality" by Nadia Odunayo, presented at RailsConf 2016, explores the concept of 'code hospitality'—a framework for improving collaboration within software teams by treating colleagues as guests and hosts in a codebase environment. Odunayo begins with a reflection on personal experiences with hosting guests and parallels those experiences with coding and team dynamics.

Key Points Discussed:

- Importance of Preparation: Just as one tidies their home before guests arrive, developers should maintain a clean and organized codebase to facilitate easier onboarding and collaboration.

- Fostering a Welcoming Environment: Emphasizing approachability and generosity when assisting new team members, akin to showing a guest around one's home.

- Storytelling through Code: Using narratives and diagrams can provide context for newcomers, helping them understand the codebase’s structure and challenges.

- Communication & Feedback: Highlighting the importance of clear communication, especially when giving and receiving feedback. Through thoughtful dialogue and open-ended questions, teams can foster understanding and collaboration.

- Retrospection and Reflection: Conducting regular retrospectives to discuss experiences and feedback, treating these interactions like farewells—an opportunity for growth and reflection.

Significant Examples:

- Odunayo shares her experience hosting a guest named Alex from Airbnb, detailing how she prepared for her visit. This anecdote illustrates how hospitality in hosting can be translated to code collaboration.

- Another story involves Odunayo and her business partner, Theo, working on a challenging project where understanding and communication became crucial, leading to the realization that visual aids significantly clarified their discussions.

Conclusions and Takeaways:

- The concept of code hospitality encourages developers to think about their roles as hosts who must ensure their codebase is accessible and comprehensible to guests.

- A good codebase should be consistently maintained, with clear responsibilities defined for its components to minimize confusion.

- Create resources—like helpful README files—analogous to guidebooks that assist newcomers in navigating and contributing to a project efficiently.

- Overall, fostering a hospitable environment through supportive communication and consideration for others' perspectives enhances team productivity and cohesion.

00:00:13.799 So I have a question for you: When was the last time you had a guest? Did anyone have someone stay with them recently? Hands up. What did you do to make their stay pleasant? Tell us. What about you?

00:00:24.269 You cleaned? That's great! Anyone else? Made them breakfast? Lovely! You guys are all lovely people. Someone even gave a guest a tent so they could sleep in the garden. Wonderful!

00:00:31.529 So I've got two stories for you about guests and hosts. Here’s story number one. Some months ago, I decided to put my spare room on Airbnb, and pretty quickly a woman named Alex booked into the room. She sent me a message saying, 'Hey, I've actually never been to the UK before, but I'm thinking I might want to move to London. I want something different.' 'Cool,' I said, 'that sounds good.'

00:00:49.469 Then she asked, 'Will you help me? I don't know if you've got any time, but if you could show me around, you know, show me things that you like, that would be wonderful.' 'Sure,' I said. So when she was coming, I made sure the flat was tidy, and I put together a little welcome pack. It had a tube map and a tourist book for London.

00:01:06.770 I prepared a little sheet with some 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 and the weather person says there's zero percent chance of rain.' So on the day that she arrived, I went to pick her up at the airport. My way wasn't too bad.

00:01:32.520 When we arrived home, I took her on a quick tour around the house and gave her the welcome pack. She really liked that. After she had rested a little bit, I took her around my area. Over the next week, we visited some popular tourist attractions, and I also showed her some quirky spots that were my favorites—places that people wouldn't typically go to.

00:02:05.930 At the end of the stay, I took her out for dinner, and I asked her, 'What were your first impressions of London? What did you like, and what didn't you like?' It was fascinating to hear her insights since she had never been in England before, whereas I was born in London and had lived there all my life. At the end of her stay, Alex eventually moved to London, which was pretty cool.

00:02:34.040 Okay, so that was story number one. Story number two: 'Rails is my city, and I've lived here all of my life,' said Theo to me one day. Theo is my business partner, and we run a company called Ignition Works. At the moment, we're working on a system that helps businesses make sense of their unit economics and decide on the next best steps.

00:02:54.049 While we were working away, I was struggling to grasp a concept, feeling frustrated and anxious that Theo was disappointed in me. His words actually made me feel better because they put my struggle into perspective. I was a welcome visitor in his hometown of Ruby on Rails, hoping to make Ruby on Rails my home too, with a friendly local by my side.

00:03:12.890 This made me think of when Alex came to stay with me; we both wanted her stay to be as enjoyable as possible. This is where the idea of hospitality comes from. By setting a theme of a guest and a host, and how we might be effective in those different roles, I think we can learn more about how we treat and respect our teammates. This allows us to onboard new people quickly and work together on our codebases in a way that's fun while remaining productive.

00:04:05.920 What I hope you take away from this talk is a new way to think about problem-solving, particularly when you're coding and picking up the next feature. I also want you to think differently about communicating, especially when giving and receiving feedback. The gist is that through code hospitality, we can improve collaboration and long-term learning across software teams.

00:04:24.370 I want to clarify that when I'm talking about guests versus hosts, I'm not referring to junior developers versus senior developers. It’s more about familiarity within whatever domain might apply—whether it's the group you're working with, the codebase, or a particular class. This idea serves as a framework for approaching these problems, and I hope it's helpful for you.

00:04:51.520 So, code hospitality—who is this guide for? We're going to try something. I'm going to throw out some phrases, and I want you to put your hand up if it applies to you, and keep it up. If one or more apply to you, put up your second hand or nod your head. Have you recently started a new job?

00:05:04.750 Does anyone have a new team member recently? Keep your hands up. Have you rotated onto a new team recently within your company? Have you recently started a new Rails project? Are you currently on a project where you're using an unfamiliar language? Have you become a manager with people looking to you for direction? This is great!

00:05:21.930 So you're all in the right place. With every visit, there’s some form of preparation. When you're receiving someone, do you ever tidy up beforehand? Some people said yes, they always clean. When you're going to someone else's house, how do you feel if you turn up and it’s messy? What about codebases? Just like a house, we need to try and keep our code as presentable as we go along.

00:06:04.530 Think about it: guests might think that they're the only ones working on the code, but guests can be unexpected, just like when Alex booked into my house very quickly. It's not great to have to spend a lot of time tidying up because another person is arriving. But if you never have a guest, it’s not great to be working with cognitive load and upfront complexity, which makes decision-making hard.

00:06:41.280 It's good to keep your codebase in a decent, clean state. What does 'clean' mean? Everyone has different ideas. For Theo and I, some things we like to ask ourselves are: Have we named things consistently? Is there something in there that's going to be confusing? Do our objects have clear responsibilities? This helps ensure we maintain clarity and order in our project.

00:07:00.660 Are we able to read our code easily? Does it make sense, or are there improvements to make? So, keep your codebase in a state that is ready to receive unexpected guests. Who has built something in London here? Many streets are narrow and windy; London may not have always been this way.

00:07:29.070 There was a Great Fire of London in September 1666, destroying seven-eighths of it. Architect Sir Christopher Wren submitted plans for the rebuilding that featured wider streets and more geometric arrangements. Unfortunately, these plans never came to fruition due to a lack of funds and buy-in from the politicians and royals, and they simply returned to normalcy.

00:08:07.410 This can happen with code too—maybe you've attempted to implement changes, but various obstacles like technical debt have gotten in your way. It's essential to understand why things aren't as they should be. If someone arrives at your messy home and you say, 'I attempted to tidy up, but I couldn't be bothered,' what does that convey?

00:08:43.169 It's vital to take responsibility for these things and think about how you might do better next time. If you have a codebase that isn't up to your desired standard, be prepared to explain the reasons behind it to your guests. For guests, ask questions, but also give your host the benefit of the doubt—understand that they are likely aware of the issues.

00:09:27.150 What type of guest are we talking about here? Will you be there to meet them, or are they going to arrive at your house alone? Maybe you’ve stayed at someone’s house and they weren’t there, leaving you instructions. In terms of code, does this relate to readme files? Readme files can be crucial for onboarding, especially when you expect someone to be preparing to access your home.

00:10:05.180 What if we had readmes that served more like guidebooks or tour guides around the general concepts present in our codebase? Think about the typical readme file you see today—detailing the Ruby version, how to create the database, how to run tests, etc. All these things help get set up and running, but are they helpful for people to continue progressing productively and confidently when they are on their own?

00:10:42.769 Here's a snapshot of a readme from Active Record, which talks about implementing the object-relational mapping pattern and includes a description, a link to a blog post, and other points about the philosophies behind it. Consider the project you are working on now: Are there particular patterns or approaches that would be helpful to explain to someone who is starting to contribute?

00:11:00.649 Here’s the readme for the Code Hospitality Guide. It includes installation instructions, usage details, contribution guidelines, and some historical context—how it came to be and where it stands now. There are approaches regarding patterns inside the code, reading materials, links to both external and internal blog posts, and walkthroughs. This type of readme helps not just with setup, but with keeping projects moving forward.

00:11:43.370 Every visit has a first meeting, just like how I was talking to a colleague who noted the saying: 'Give a person a fish, and you feed them for a day. Teach a person to fish, and you feed them for a lifetime.' But what if that person is starving? They may need fish first because you might not get a chance to teach them right away. We need to find a balance between giving a helping hand and promoting self-sufficiency.

00:12:03.649 When someone arrives to work on your codebase, it's essential to be generous with your time and attention, wanting your guests to be self-sufficient as soon as possible while still providing that helping hand. Is there something you know a lot about that others don’t? Can you share it through a long-form workshop? You should clarify that they can ask you anything at any time.

00:12:55.770 It's always good to encourage questions, whether it’s about something you’ve developed or a decision someone else made. It’s also helpful to ask if there’s anything they would like to see that you haven’t shown them. Be mindful of your cues to others—if you’re burying yourself in work and putting on headphones, are you signaling that you're uninterested in interruptions? If that's the case, be sure to let them know when your next availability is.

00:13:40.399 Just like when I went to pick Alex up from the airport, which went a bit out of my way but set a helpful tone, demonstrating generosity and concern can help new teammates feel at home. It’s important to show them around your codebase and provide accessibility without rushing them through it. How do you give them tools to understand your codebase?

00:14:09.810 I had people tell me they'll start with the tests, while one woman from an insurance company said she would start with the insurance policy object and branch out from there. Curiously, some participants also mentioned the effectiveness of drawing diagrams. I believe this is important. Telling a story about the state of your codebase can really help newcomers understand its context and the flow.

00:14:57.350 You might draw diagrams about the objects in your code, how they interconnect, and also consider business concepts. For instance, Theo and I were recently working on a nutrition project, and we learned a lot about nutrition theories and dietary practices, which helped inform our development process. You can string that narrative together to provide a clearer picture for your guests about the codebase.

00:15:30.710 So, when you're showing someone around your codebase, think about the story of its creation. Also, there will always be activities during a visit, whether you are collaborating with your guests or whether they’re independently working. Let's analyze the work done together—a user story may prompt you to come up with questions.

00:16:03.800 The truth about Rails is that everyone’s understanding and approach vary. If I asked you to draw a map of Rails, it might look different to everyone drawn by someone who has been programming in Rails for years. The point I’m making here is it’s not about how well you understand Rails but how you perceive the domain and why you see it that way.

00:16:30.880 Consider the next feature or user story you're assigned to. If you’re familiar with the codebase, you likely have a clear starting point. However, does your guest see it that way? Let’s say the story is: 'As a user, I want to get inside the Tower of London.' You're picturing needing a plane or parachute, while your guest thinks it’s a simple walk through the doors. These differing perspectives can lead to miscommunication during problem-solving.

00:17:44.90 This reminds me of a time when a colleague called asking for directions back home. I assumed she meant the Tesco I frequented, but I learned there are multiple locations with that name. It's critical when coding that you understand each other's starting points and perspectives. This makes it far easier to work effectively on a problem.

00:18:11.140 Similarly, while working with Theo, we faced a problem with no clear resolution. It wasn’t until we started illustrating through diagrams that everything became clear. By visualizing our conundrum, we realized the order of operations was unclear and worked on that until we came to the same understanding.

00:18:42.300 Drawing these diagrams provides immediate communication and serves as a way to initiate conversations. Questions will always arise when working with people. Reflecting on our conversations may reveal how we can clarify concepts and help resolve uncertainties.

00:19:06.580 For example, when Alex asked me for directions to a pharmacy, I gave her baseline instructions based on assumptions without confirming her understanding. This shows the importance of ensuring that individuals fully grasp how to navigate tasks, fostering a more comprehensive dialogue about approaches. By facilitating these conversations, we can maintain continual clarity and understanding in our exchanges.

00:19:56.690 When you begin tackling coding challenges, start by discussing methodologies you've employed previously. Be transparent about how things have worked out along the way. It helps demonstrate a collaborative atmosphere and ensures everyone feels included in the project.

00:20:28.280 Ultimately, it’s time to say goodbye, whether your guests are leaving your home or someone is finishing up for the day at work. Remember that I took Alex out for dinner to ask her about her experience—this is akin to a retrospective in the workplace where teams gather weekly to reflect on past performance.

00:21:06.490 I'm not just referring to team retrospectives; I believe we need more one-on-one retrospectives. After pairing with someone for a while, it’s useful to discuss what went well and what could be improved. Giving feedback can be challenging; however, it is essential for growth.

00:21:49.520 To make feedback easier, frame it around emotions. Reference your observations and the underlying needs associated with those feelings to create a foundation for conversation. For example, instead of saying someone underperformed, you might express feelings of disappointment while discussing the situation and seeking future improvement.

00:22:38.040 The goal is to maintain a no-judgment environment while drawing attention to where needs are not being met. This approach allows the recipient to understand the issues without feeling attacked. Focus on expressing feelings based on observations and needs rather than passing judgment.

00:23:25.780 So, that was code hospitality. Here’s a brief recap: When preparing for a visit, clean up your codebase as well as you can. For issues that can't be resolved, be prepared to explain why they're not up to standard while fostering higher-level discussions about the concepts you're using.

00:24:06.850 At your first meeting, be patient and generous with your time. Display eagerness for questions and encourage guests to ask their own. Provide a narrative of both the challenges and the accomplishments of your codebase while utilizing visual aids such as diagrams to facilitate understanding.

00:25:01.420 When working together on tasks, initiate discussions at a high-level viewpoint and collaboratively drill down to specifics. Ensure that you check in with your peers to align on perspectives so you’re on the same starting point. With farewells, conduct those one-on-one retrospectives to promote reflection.

00:25:48.660 Keep communicating about feelings observations and needs as you develop your rapport with team members. Most importantly, keep working closely with others and collaborate often to improve comfort and proficiency in your environment.

00:26:30.330 So, who’s ready to take on the code hospitality challenge? You'll need a colleague, preferably someone new to the environment, or it could even be someone you've worked with for years. Set aside three hours in a given day to work on a well-defined feature in your backlog.

00:27:01.460 This doesn't necessitate completion; just make sure it's clear what you're working on, ideally something easily readable. During this time, dedicate some of your hours for preparation—consider possible roadblocks and discuss the problem at hand.

00:27:53.600 Draw diagrams to visualize your perspectives. Ensure that both of you are aligned on what the problem entails. The implementation phase will then primarily consist of coding closely together, ideally from the same machine, exchanging roles while remaining communicative throughout.

00:28:32.500 To conclude, dedicate time to reflect at the end of your session to gauge how things went—what worked, what didn’t. If you manage to complete everything within three days, you might even win a special prize. Let’s hear your insights on code hospitality through tweets, diagrams, or snippets!

00:29:19.780 If you have queries concerning the logistics of pairing or any other communications aspects, I encourage you to engage with me or reach out to my colleague. Lastly, read 'Nonviolent Communication' by Marshall Rosenberg—it offers tools for channeling compassion and understanding.

00:30:00.220 Thank you all for your time, and I hope you find value in code hospitality as much as I have. How was your stay?

00:30:24.460 To address the question about beginning with feelings in feedback, it’s essential in identifying what's wrong. Reflecting on why you feel a certain way helps shape the discussion toward solutions, fostering collaboration while emphasizing understanding.

00:30:54.320 In situations where you face power differentials, consider using open-ended questions that encourage others to express their needs. This method dismantles barriers and shifts the dialogue toward shared understanding. Ultimately, regardless of statuses, fostering a welcoming discussion environment benefits everyone involved.