Engineering Tenets: Communication is King
In our new 4-part series, Director of Engineering Spencer Norman explores the ways in which Reaction Commerce’s engineering tenets lay the foundation for a successful technology-first organization. Each week, Spencer will dive into one of our four overarching themes—communication, character, competence, and cooperation—along with the core values that drive each principle.
As a distributed team building open source software, strong communication is the cornerstone of our organization. Good communication keeps team members—many of them physically located on different continents—in sync. It helps us collaborate with our open source community. It also pulls us forward in one direction, even when we’re working on different tasks (all of which ultimately contribute to our unified goals).
In this blog post, I’ll explore the 4 values that make up effective communication here at Reaction Commerce: thoughtful feedback, a bias toward public discourse, clarity, and focus.
We believe that feedback should be timely and thoughtful, given as soon as possible. In the ideal case, this would occur immediately following an event or action. Sometimes giving accurate feedback requires research or more in-depth thought. In those cases, it’s acceptable to let the other person know that you’re working on a response, and will be able to give more feedback after you’ve had time to consider things. Feedback is not always immediately available in a distributed team, but we try to hold each other accountable.
When asking for feedback, whether in the form of a code review, blog post edits, bug report verification, or a performance review, specificity is highly valued. When asking for a code review, identify specific sections of code to focus on. Are you wondering if there’s a better way to write a part of your code? Call that section out specifically! If you don’t, the reviewer may not be certain what your goals are.
Thoughtfully-giving feedback means focusing feedback on specific work, actions, or events—never on someone’s character or humanity. A great programmer can and will write bad code from time to time. Focus on how to improve the quality of the code being reviewed. And if you’re the one whose code is being reviewed, remember that it’s not personal. It can be easy to conflate feedback about your code with feedback about your abilities as a programmer or your qualities as a person, but try to understand that your reviewer has good intentions in mind. The best feedback cycles will involve both a reviewer and a reviewee focused on delivering the highest quality work.
Building open source software requires open discussions about the technology we’re developing with the community we’re building it with. That’s why Reaction has a bias towards public discourse, which we believe to be our ideal form of communication. As a distributed team, our internal communication benefits substantially when we can point towards established docs, GitHub issues, or Gitter discussions, rather than trying to recall a conversation that occurred over a call.
How does this bias manifest itself? First off, we believe that no technical discussions should happen inside of a direct message or private chat. In general, discussions should be public. Sometimes, that means realizing when your one-on-one discussion has become a conversation that might benefit others in the organization or community, either now or in the future, then creating an issue on GitHub. For other discussions, that may mean instead of giving or requesting feedback about a specific pull request via Slack, you give/request that feedback on a pull request instead.
We also believe that documentation is the highest form of communication. This is why we require documentation for all new functionality. It may take slightly longer to write good docs than a DM, but you’ll only have to say it once. Plus, it will immediately benefit the entire organization and open source community, rather than just the person who asked the question initially.
Our bias towards public communication is one of the reasons why we host regular community calls. At our community calls, we share our technical roadmap and have discussions with community members about where we’re going.
Public communication is also the reason why we set aside a portion of our engineering time to write technical blog posts. Our blog posts outline our architecture choices and define the impact those choices will have on our community. Writing these posts takes time away from building our core product, but improves clarity and institutionalizes knowledge to the extent that it’s worth it.
With our focus on public discourse, it’s easy to get overwhelmed by the sheer amount of information that funnels through our GitHub issues, PRs, and releases on any given week. In order to make sense of this information, we believe that every engineer at Reaction and in our community should expect and demand clarity in all aspects of communication.
We’ve recently updated our documentation to clarify what a good PR looks like, along with our PR template. We’ve updated our Issue template, and soon our docs will specify what goes into writing a great bug report or feature request.
When we’re scoring issues during our planning meeting, it’s essential that we’re all on the same page about what constitutes resolution for a given issue before we score. When every member of the team is empowered to demand clarity before an issue gets scheduled in the backlog, we ensure that we don’t work on issues that have too much ambiguity. And since we’re a globally distributed team with a global community, our emphasis on clarity involves not making any assumptions about the engineers looking at the code we’re writing, namely whether or not they’re native English speakers.
Every line of code that’s committed to the Reaction codebase is reviewed by at least one engineer. Reviewing code can easily take up a huge part of our day-to-day, so to keep from getting bogged down, we do require a little bit of work from the code submitter before even considering acceptance into the code base. Some of these checks are automated (CI build, tests, linting), while some are manual: fill out PR template, write jsdocs, double-check and document code. Only after the pull request fulfills these prerequisites—and passes all of our automated checks—will we enter it into someone’s review queue.
With all of this emphasis on communication and documentation, it may seem like there isn’t any room for engineers to focus and get in the zone. That couldn’t be further from the truth. As an organization, we place enormous value on clearing our schedules so that we can get hard things done.
We believe that interruptions are costly, which is why significantly long, contiguous blocks of focus time are vital to the health of our organization. Every engineer is different, but I know that I need 4-hour chunks of uninterrupted time to get any significantly difficult work done. If I don’t this time available to me during the day, I end up working evenings, when Slack is quiet.
As an engineering organization, we hold meetings as a last resort, mainly to discuss challenges or to come to a consensus. If an email works, then we won’t hold the meeting, and when we do, we do everything we can to end meetings early so that people can get back to their focus time. Because of this emphasis on reducing or eliminating as many meetings as possible, we expect all participants to be fully engaged, since everyone at a meeting should be there for a reason. Meetings also end with action items, so each of the participants leave with a clear understanding of how to move forward from there.
Effective, mindful communication can be challenging at first. Erik, our core team engineer, even wrote a whole blog post about the unique challenges 24/7 transparency can bring. Still, at the end of the day, it’s worth it. We’re not just building a commerce platform, after all. We’re also building a team.