How To Be A Good Guest (in another team's codebase)

For nearly twenty years, I have regularly found myself (temporarily) in another team's software codebase. From being hired as a contractor, to providing emergency technical support, to helping companies understand the health of their application via a code audit...I have learned a few things (via trial-and-error) about what to--and more importantly--what not to do while being a guest.

This topic is near-and-dear to me. Recently, I was a guest on the Developer Tea podcast and we got deep into this topic. We got deep into it needed to split it up into two episodes!

🎙 Listen to part 1 and part 2.

Are you a freelancer or contractor about to temporarily participate in another Engineering team's project? Here are a few considerations for those first hours/days of being a guest.

(FWIW -- you can apply this to being a new full-time team member, too!)

Document Your Goals 📝

As a contractor, the company has likely brought you in to assist with something specific. What was the problem that they were encountering and/or feared they would encounter in the future?

• Are you there because you have specific expertise that they have limited knowledge of, in-house?

Do they need help upgrading their Ruby on Rails application and you've helped dozens of teams do that? Has their application become unstable? Is their test suite taking far too long to run and they need you to help them speed that up?

• Are you there to temporarily offset needing to hire a full-time engineer? (Aka staff augmentation)

Let's dig deeper into this one. Why do they need to bring in additional help right now? Did they recently lose someone? Has their team's Sprint velocity drastically slowed down? Are they needing to scale up for the next few months?

Whatever the case...you should understand what their underlying rationale is. You need to capture their WHY behind the decision.

If there is one thing that I've learned over the years...it is that when there are a lot of moving parts, we sometimes need to remind our clients of their own decisions.

As much as you would like to believe that everyone on the team you're temporarily joining is on the same page (and/or even support the idea)...it is wiser to assume they are not.

That's okay, though.

(Let's find comfort knowing that humans have this funny way of moving forward, together, despite an unpredictable level of chaos.)

This is why it is important for you to clarify what your goal is here. You will need to own the success of it. This is what they are paying you to do.

🚫 Anti-pattern: Being passive. Showing up on Day 1 and asking, "what do you want me to focus on? When will someone assign me tickets to work on?"

When you show up on Day 1, you'll want to reiterate why they hired you. Frame your questions around that.

"My goal is to help your team address X & Y over the next few weeks. Who would be the best person(s) to help me get up-to-speed on the current situation?"

Once you identify who your internal domain expert is, you'll want to reach out to them to schedule manageable blocks of time to a) reiterate your goals b) listen to them share their perspectives/concerns (capture these, too!) c) learn more about their capacity constraints, and d) ask them if there are other people on the current team who might also be helpful to help you reach your goal(s).

Make it a SMART Goal ⚽️

Take a moment to think 3-4 weeks into the engagement. You're having a one-on-one chat a team lead and they ask, "how is that project of yours coming along?" ...how will you respond?

Ideally, you should be able to respond with, "ON TRACK" or "OFF TRACK."

Software Engineers have been known to be risk-averse (for good reason!) but when we're hired guests, we should aim for removing ambiguity and/or diving too deep, too early, in a discussion. While we have to balance a lot of nuance in our jobs, let's keep be mindful to not overwhelm the person we're speaking to unless they are truly curious to get into the weeds with you.

We can do this by trying to clarify them via SMART goals.

💃🏻 ProTip: "We're on track!" > "I'm on track!"
(...remember, you are part of a team)

...wait, WTF are SMART goals? 🤔

Great question!

🧠 S.M.A.R.T. is a mnemonic acronym to capture our objectives by answering whether they are Specific, Measurable, Achievable, Relevant, and Time-bound.

Here is a helpful guide on writing achievable SMART goals by the fine folks at Atlassian.

Share your SMART goal 🥅

Rather than assume everyone shares the same understanding of the goal, it is important to share what you've captured with your new team members.

There are times when your new teammates might not believe a goal is achievable...especially if they've tried (and failed) to get there in the past. This is your chance to solicit input.

If it later comes up that they didn't share something useful when given a chance, then it'll be something you can recalibrate with them.

Avoid assuming that this is malicious. It's plausible that it wasn't on their mind at the time and they remembered it later.

Getting Into Their Code 👩🏼‍💻👨🏻‍💻

Let's assume that they are going to invite you to their code repository(s) and you'll be aiming to get their code up-and-running in a local development environment.

What kinds of changes are happening in their code?

One of the first things that I do after cloning a repository is to start browsing the output from git log. I'm looking to learn more about their team.

• 📝 Do they follow commit message conventions?
• 📖 Do the commit messages help tell a story?
• 🚢 Are they shipping new features?
• 🐛 Are they trying to squash a lot of bugs?
• 🎳 Who has been actively pushing code changes into the main branch(es)? (The bowling ball felt fun)

Using other fancy git commands, you can find files/areas of high churn, explore the maintenance (or lack thereof) of the test suite, how often documentation is updated, etc.

Will you be interacting with these people on the team in the coming days? Take note of a few observations.

"Wow, it seems like you've worked on a big feature recently. What was involved with that?"

"It looks like you've been helpful in squashing a lot of bugs recently. Is that a big part of your role here and/or do you rotate that responsibility across the team?"

How do you get their application running (locally)?

If you're lucky, the team will have up-to-date docs that'll help you quickly get their application running in your local dev environment. You might consider timing how long this process takes.

It can be helpful to report this back to a team lead to see if they are surprised by the information. If the team is encountering scaling problems, this can be one of those bottlenecks that slow down other new hires/contractors, too.

If anything, they can use this data point to properly map out a realistic onboarding timeline. Similar to capturing how long it takes for your test suite to run, how long deployments take, uptime... this is another useful metric to measure.

Recruit a spin-up buddy, if possible

When my team at Planet Argon are hired by a client, we try to have two of our engineers pair up on the process of getting the application running, in parallel. This way we can try to spot gaps in the documentation, debug issues quicker, and avoid having a scenario where one person who gets out ahead of the other.

If you are a solo guest working within a new-to-you team -- it might be a good idea to see if you can grab someone on the team to pair with you on setting up their application.

🤹🏻‍♀️ ProTip: If you want to get a feel for how complicated this process might be...ask one of their team members how anxious they would feel if their laptop died right now. 🙀 If they had a brand new laptop with a fresh operating system installed...how disruptive would that be for them? This is someone who has experience with their application and the underlying dependencies. If it is that scary to them...think about all the unknowns to someone brand new?

If you need to go rogue...

Should you not need to recruit someone to help you get up-and-running, then by all means, go on this solo mission but I encourage you to be extremely careful about this.

I've witnessed this a number of times over the years (by myself and members of my team). We'll begin to dig into our client's Ruby on Rails application, getting things up and running, and we forget to do the following.

Share our progress!

If the spin-up time takes a while, we would benefit ourselves (and our new teammates) by reporting on our smaller milestones.

A quick list of what's been accomplished and what remains should be simple enough to share. It'll give the team a chance to highlight if anything is missing from your list.

Update the documentation when we find any gaps and/or inconsistencies.

Our fresh perspective of reading and using the existing docs is a perfect time for us to create a new branch and commit updates so that we have a fresh pull-request to send when we're wrapped up.

🚫 Anti-pattern: Using language like "fixed" in documentation updates. Language like "updated" should suffice. Fixed has a different connotation. Assume it used to work fine at one point.

Acknowledge the great docs that exist!

While you are working your way through the documentation, if you are finding it to be well-organized and helpful, consider taking a moment to see who on the team was responsible for those updates. Look at the revision history. Reach out to the people who helped make your life easier today.

"Hi Kathryn! As I'm a frequent guest in other team's codebases...I see a wide spectrum of documentation in terms of organization and usefulness. I wanted to let you know that these are some of the best setup docs that I've seen. Thanks!"

"Oscar - I hit a problem while trying to install all the RubyGems because nokogiri was failing to build. I was about to start debugging it but noticed you had a helpful note in the docs about how to fix the dependency problem in Mac OS Catalina. You saved my afternoon!"

(Obviously, only do this if you found the documentation helpful; we don't want to placate anyone! 🙃)

The effort that we put into maintaining documentation tends to feel under-appreciated. Let's do our part to highlight when docs make our life easier!

🚫 Anti-pattern: Spending a ton of time trying to figure out how to fix a problem during the up-and-running phase without reaching out to other team members to ask if anyone had encountered it before.

If you spend several hours trying to Google for an answer on StackOverflow -- it is possible that someone on the team has but hadn't captured that in the docs before. This will help convey that you're humble enough to ask for assistance, which the team you're temporarily joining finds value in. We hope.

Be Vocal As You Dig into Your Project Work

Now that we're in a position to get crackin' on our work, it is tempting to put our headphones on and allow ourselves to get lost in the task-at-hand. While getting to a state of FLOW is important for productivity...we run the risk of being far too quiet for too long.

If the team has a good cadence on regular check-ins (do they have stand-ups? Slack channel updates?) then this might not be too much of a concern. Should they have a loose communication culture then we should be proactive over-communicators...especially in those first days as a guest.

What did you accomplish yesterday? What are you aiming to accomplish today? Do you have have any blockers?

Find out who might be able to help you remove a blocker. Do that earlier in the day so that you have a better chance of getting time scheduled with someone who can help.

🚫 Anti-pattern: Struggling to make meaningful progress in the first few days. We don't want our new team members to wonder what you've been up to. (While we can talk about how important it is for them to trust you...we need to earn some of that, too). Silence invites people to make assumptions. Influence the narrative!

As consultants, we are often hired for our expertise. We should avoid interpreting that as them expecting us to have all the answers. Let's just strive for having good questions.

Ask for Context Not Rationale

"Heya, quick question about this feature I'm starting to work on. Why did y'all design/build this it like this?"

🤦🏻‍♂️ Don't be that person.

Trust me, I've learned the hard way.

This is an ineffective way to win over your temporary teammates. Firstly, we shouldn't assume that the person(s) we're talking with had a hand in the design/building of something. They might have inherited it. They might agree with you if something was poorly designed... but I encourage you to be open, empathetic, and curious.

"Heya, I have a quick-wish question about this feature I'm starting to work on. Would you be a good person to help me get the scoop and/or backstory?"

Invite them to fill-in history. Listen. Assume that those who previously worked on it did the best that they could given the time/budget/resources available. Start from an assumption that they might agree with you.

You're there to help improve it not to be the person who can only point a flashlight 🔦 at it.

Note: if you find that they don't see a problem with it... you should find a way to have that collaborative conversation to explore that together. YMMV.

Leave the Team Better Than When You Found It

The long-term success of the team you're temporarily joining is not your primary responsibility. That isn't to say that you will not have an impact on it. With any team, it will change to a varying degree as people interact with it.

As consultants/contractors/freelancers...we have a unique and value perspective when we interact with different teams. If we're curious enough, we can spot patterns in the teams we participate in and share our observations.

If we care enough, we can highlight the things that you see are great about this team. The members of the team might be have been insulated by their team's bubble for a while. They may forget what it was like before.

On the flip side, if things seem toxic, let's find a meaningful way to convey that to the relevant people. We might not think it is our responsibility...oftentimes, it is not...but, again, the bubble might need to be stirred up. (I'm not advocating that you try to burn it all down...but you can share what you see is working or not compared to other teams you've been part of). Be mindful to not pre-diagnose the situation.

Raise underlying issues (versus pointing out the culprit).

🚫 Anti-pattern: Offering solutions versus experiments.
Compare "At another client, they used ABC. You should use ABC here..." versus "they experimented with ABC and had good success. Have you considered experimenting with ABC here before?"

Again, we're here to ask good questions.

Closing Thoughts

I know that I am scratching the surface at this topic. If you found yourself skimming this, let me summarize this into a few closing thoughts.

As a guest (in another team's codebase), please remember that you are a temporary member of that team now. Despite your technical skills, your goal is to be a productive and helpful contributor.

Be goal-oriented.

Avoid playing the hero.

Give credit.

Confirm assumptions.

Share kudos.

Stay organized.

Be thoughtful.

Propose experiments.

Be curious.

Be a good guest.