Joining a new team is an exciting opportunity and a cautious endeavour. You don’t quite know how your teammates work, what they expect from you, or how they’ll react to your contributions. This can also be your chance to shape how things are done based on your own experiences. Discussing “team norms” has been a popular concept for newly formed and growing technology teams. It means that expectations are laid out collaboratively and we do our best to follow them. Working relationships thrive when we agree to best practices together, and talk about and update them regularly.

Keep in mind:

• This is a living document: we’ll update it as we learn, grow, and bring on new team members with their own ideas on how to be an effective team.
• We’re weaving in examples to help illustrate our principles. Keep in mind that the specifics don’t matter as much as the overarching aim.

Our Principles

✅ Helping our teammates ship their code is as important as ours

It’s important to take breaks throughout the day to get a sense of what our teammates are working on. While we value flow & focused work, we know that beyond shipping our own code, the following kinds of contributions are equally important:

• Providing feedback on code ready for review or green-lighting a PR
• Reading & providing feedback on a tech spec or Request for Comment
• Keeping on top of what our teammates are planning to work on and proactively helping with potential roadblocks
• Chipping in on Quality Assurance for a teammate’s contribution if you think you have more context or suspect an edge case was missed

💬 Context & communication is key

Software is a living thing, constantly evolving along with its requirements. Team members are often deep into very different business goals or technical problems, but we still want to collaborate across the things we individually own so that we’re benefiting from each other’s experience & insight. We think about our teammates by providing ample context:

• In PR descriptions we’re clear on the:
  • Why: a description of the problem we’re solving with a link to relevant tech specs or business requirements
  • What: pointing out the most important changes being made or the rationale for an approach that was taken
  • How we tested: detailing the specific scenarios and edge-cases we tried to account for, along with the method we used to test (ie: the user state we had to be in, the platform or environment setup required)
• We recognize that future teammates may need to change the code we write or understand the decisions we made. We understand that our PR is a historical artifact of our contribution
• In shipping our change we’re clear to stakeholders about what they should expect:
  • Which build or release the change will be in
  • Whether the change is “turned on” or will only be visible in certain situations
  • How we’re monitoring for performance if needed
• We offer to pair on more complicated code reviews or provide a video screencast overview of the change if needed
• We recognize that submitting a PR is a call for help, and we should make it as easy as possible for our teammates to gather the context we had in producing that code so that they can be effective in their review
• Providing ample context can take more effort than the code change itself, and that’s fine!

🤝 Substance over style