Written communication for remote engineering teams

Paolo Lim - Founding Engineer

Working remotely is not new at Flow, but the pandemic has forced changes for the better with our engineering teams. Before the pandemic, almost everyone was based in our headquarters in Hoboken, NJ or our office in Dublin, Ireland. While Slack and email were available, most communication happened the “old fashioned way”, walking over. Meetings, discussions, and other interactions happened mostly in-person.

Just like everyone else, the pandemic changed all of that. An entire company working mostly remotely for an extended period of time is different from occasionally working from home, but mostly in the office.

Three of the big changes that have made asynchronous written communication far more important: 

  1. No longer can one just “walk over” to someone’s desk 
  2. Assume that someone was online all the time
  3. Assume that someone is interruptible on our time 

Let’s imagine two different scenarios:

Pull Request (PR) code reviews: In an office-centric culture, one team member works on code changes, then publishes a PR. If the PR is sufficiently complex, then one or more team members may huddle together to discuss the PR. Some even suggest that if a conversation in a PR is longer than 10 exchanges, that everyone just walks over to talk it through.

Person-to-person conversations: Previously, if someone wanted to bounce ideas off each other, or talk through a complex issue or problem, it was natural to walk over. Most people found it easier to “explain” an issue by talking about it, rather than documenting it in a systematic way. Once everyone is on the same page, the problem or topic would be resolved by those assigned to it.

The transition to fully-remote work meant that while there were “general working hours”, most people would communicate asynchronously. Ambiguous requests or communication means tasks could get stalled because people are unclear on expectations or next steps.

For engineers starting pull requests, several teams have adopted a standard template to include a brief description and explicit post release verification steps. It looks a bit like this:

This template makes it clear:

  • What the problem is
  • Summary of the overall approach
  • A list of explicit items to check - this can be long
  • BONUS: This is easy to read and reviewers don’t need to spend time being convinced that the change worked as expected!

For Person-to-person conversations, Flow utilizes asynchronous tools like Slack and JIRA. Asynchronous communication happens through JIRA, and we have attempted to push all communication around issues and features here. For issues, we use “incident” or “stewardship” templates. Remote work has reinforced the idea for people reporting an issue to clearly write down and describe an issue by stating the list of steps to reproduce the issue, explain the expectation, and explain how that expectation was not met (ie, the bug).

This is what it looks like:

It is expensive for an engineer to respond to a ticket that simply says “feature XXX isn’t working”, with a screenshot of an error message. It provides very little context or understanding of how that state was reached. By introducing and enforcing templates for issue-based JIRA tickets, engineers are able to reproduce an issue, and resolve it much more quickly - while being able to verify the fix for themselves.

We have many other examples at Flow of changes brought about by fully remote work but hopefully these two highlights are helpful.