RFC: Standard Communication Tools
|Summary||Standardize communication rules and establish common norms of usage|
|Created||October 17, 2019|
|Status||WIP | In-Review | Approved | Obsolete|
|Contributors||Kevin Fishner, Mitchell Hashimoto|
HashiCorp is a remote-first company, meaning we optimize our workflows for decentralized remote teams. To support this we depend heavily on a wide set of communication tools. Each tool is meant to solve for a different set of challenges and use cases. For new employees joining the organization, it can be hard to know what the proper norms are and the etiquette for each of these tools. The goal of this RFC is to provide prescriptive guidance on the tools, norms, and etiquettes.
There is a broad set of tools at HashiCorp and some of them are used across the entire organization, while others may be used in a specific department or function. The key tools that are used across the organization today are:
These tools can and will change as our organization changes. This RFC is meant to capture a snapshot in time of the tools we use and their best practices. Over time, we will move and keep this information updated.
Communication tools serve two general purposes — decision making and social interaction.
For decision making these tools are ordered from most ephemeral to least, and should be treated accordingly. In the context of making decisions Zoom, Slack, and email are for conversations and discussions about decisions, while Google Docs is for documenting decisions as the source of truth. Asana should not be used for making decisions, but for carrying out decisions that have been made.
|Tool||When to use it|
|Zoom||For real-time, high bandwidth discussions. Should be used for cultivating a discussion rather than transactional asks.|
|Slack||For real-time, asynchronous discussions. Useful for when team members are online and to have a quick discussion that does not require depth.|
|For asynchronous discussions that require longer-form prose and extended thought. Useful for when you want to ensure information is read, or a response is needed.|
|Google Docs||For documenting decisions as the source of truth.|
|Asana||For project managing after plans have been made.|
Zoom and Slack are the main tools for social interaction. Both are great for cultivating relationships, sharing common interests, and getting to know colleagues. Think of them as "virtual water coolers", but be aware that these water coolers can have a much wider reach than their real-world alternatives.
Zoom is the primary video conferencing software used internally. For people in the SF office, conference rooms are equipped with “zoom rooms” which allow them to dial into a Zoom meeting and have multiple people in the room to participate.
Video conferencing is best suited to have a real-time conversation, where available people can participate synchronously. This is great for discussing topics that may require rapid back-and-forth iteration to brainstorm, discuss, or come to an agreement. Trying to have those same conversations over Slack or Email results in very long threads that are hard to follow and digest.
Because of the synchronous nature of video conferencing, it can be difficult for distributed teams to align on time zones. It may be that certain team members are unable to make it because of scheduling conflicts, time zones, PTO, etc. Zoom supports a “record to cloud” feature that allows the meeting to be recorded easily. The video and an automatically generated transcript should be shared with any attendees that were unable to participate. It is unrealistic to expect people to rewatch a full meeting consistently, so try to take notes and link to important points in the meeting when referencing the video.
For conversations that may want to be referenced later, because they were important brainstorming sessions or otherwise, you can link to the recording from meeting notes or a project management system for future reference. Information that you want to retain long-term should be copied and transcribed into a long-lived document for ease of consumption.
Video chat is fairly intuitive, but there are a few things to be aware of:
Slack is the primary chat software used internally. It is best suited to have ephemeral conversations that are real-time and asynchronous. It’s expected that people are generally on Slack when they are working, but not expected that they read all the backscroll and new messages they might have missed. In that sense, Slack is like talking in a physical room, you don’t expect people who are not there to hear you.
Slack is best thought of as a conversation mechanism, so we should not use it to document decisions, designs, or any content we want to reference long term. Instead, those decisions should be captured in a more appropriate form, such as a Google Docs or a knowledge management system like Confluence. This makes it easier to reference without having to read through lots of potentially irrelevant chatter in the future.
Slack threads should be used to follow up topics of conversation in almost every scenario. This makes the backscroll easier to manage for people who wish to check it and also allows multiple concurrent conversations without stepping over each other. The 🧵emoji is often used to denote a thread will be used or should be used, and you are encouraged to start a thread when you think more conversation is expected.
For conversations that require lots of back and forth to iteratively discuss, consider using Zoom instead. Otherwise the conversation can become hard to follow and noisy for other members of the Slack channel. For conversations that you want all participants to see and participate in, use email, since it is not expected that people will read all the Slack messages that they’ve missed.
Slack also provides a few different types of channels you can communicate in:
When creating a new channel, you should follow a well established naming scheme. If you look at the existing channels, we use a prefix to indicate what the channel is for:
Slack can be new for many people, especially in the context of a remote first organization, so there are several important norms to be aware of:
Email is best suited for having asynchronous conversations, where you do not expect a real-time response. It is expected that people are reading and responding to their email in a timely manner. This makes it a good medium for when you want a high assurance that people have seen something and they have an opportunity to respond and give feedback. Unlike Slack, it is very friendly to timezones or people who may be away from their desk (traveling, in meetings, etc).
Due to the length of time between emails, it is not a good medium for active discussions. Those are likely better suited to either Slack for short and simple conversations, or Zoom for longer more complex conversations. The outcome of those discussions can be summarized and captured in an email for other participants, which is more efficient than a very long email chain.
Internally we use Google Groups to create mailing lists. These are useful if you frequently expect to send emails to the same set of participants. This makes it easier to send to all participants with a single address, rather than remembering all the relevant stakeholders. It also provides a way to see all the messages sent to a group, so it is helpful for new members joining or people who may want to just view the recent conversations.
All Google Groups are indexed by Cloudsearch (cloudsearch.google.com). This makes it easy to search and retrieve information that was discussed within groups. Joining a group and disabling email notifications is also a great way to "subscribe" to information and make it available via search.
Mailing lists should use a naming convention similar to the Slack rooms documented above. This makes it easier to remember the name of the mailing list and to infer what the purpose is.
Most people are familiar with Email but there are some internal norms that are important to be aware of:
We use the G Suite extensively, including Docs, Presentations, Sheets, and Drive. This provides a way to easily share and collaborate on documents for a distributed team. Documents are particularly helpful for asynchronous review, as you can read whenever time allows and provide comments and suggestions. This makes it very remote friendly to support timezones, conflicting calendars, or being away from your desk.
The document format is ideal for long term knowledge capture, since it strips away the unnecessary conversation and the various iterations into a final form. We should strive to capture any of our important decisions, processes, proposals, designs, etc as a document which can be shared and searched.
To make organizing documents easier, we use Team Drives in Google Drive heavily. These are effectively “folders” that can be shared with particular people, groups, or the broader company. These provide a way to organize the files hierarchically, so that they can be easily discovered. Generally you should create a team drive for each department or functional group, so they have a space to collaborate and share files.
A common mistake is to attempt to find existing documents using "Google Docs" or "Sheets" directly. The organizational structure in these direct products is unintuitive and search is subpar. Instead, use Drive directly which has a hierarchical folder structure, or use Cloudsearch.
For common types of documents, we have templates that should be used. These are meant to ensure a common way of describing problems, design decisions, market evaluations, and more. The most common formats are the RFC (Request For Comment) or PRD (Product Requirement Document). There are several others that can be found in the template library when you create a new document.
There are several important gotchas with using Google Drive that you should be aware of:
We use the G Suite extensively for office collaboration, including Gmail and Google Calendar. Using Google Calendar makes it easy to manage a personal calendar, or group calendars that are shared by multiple users or teams. By default, personal calendars are visible to other team members, which makes it easy to schedule meetings with one or more people by finding free slots.
However, this means that we should be cognizant of how we use our calendars, who can see them, and how we should interact with each other. We want to keep the cultural norm that calendars are public and visible, to make it easier to collaborate and coordinate. If you have sensitive meetings that should not be visible, those should be marked as “Private” visibility.
We should be similarly respectful of other people’s calendars. If people mark time as being out of the office, or offline because of time zones, those blocks should be respected. If a meeting looks interesting to attend, we should ask the host before joining. The best advice is to treat others' calendars as you’d like them to treat yours.
There are several important gotchas with using Google Calendar that you should be aware of:
Asana is a project management tool that is used extensively for a broad variety of tasks. Teams will often use Asana to coordinate work and ensure they are prioritizing effectively. Cross-team projects can also use Asana to ensure multiple teams are up-to-date and effectively coordinating their efforts. It can also be used as an individual task manager, where you can store private tasks to stay organized.
Decisions should not be captured in Asana because it is not a long term knowledge store. When tasks and projects are completed, the entries are archived. This means its best for short term use and coordination, where the decisions are captured in a different system like Google Docs or Confluence.
To make organization easier, you can create a “Team” within Asana. This allows you to invite other people to collaborate on a collection of projects and tasks. Within a Team, you can create a series of Projects. Each Project has an ordered set of Tasks. This allows you to capture different workstreams as independent projects to make it easier to visualize and understand.
For common types of initiatives, you can create a “Template” project. This has a predefined set of tasks, and allows you to easily create new projects each time. This is useful to ensure steps are not missed and to create a repeatable process.
In general, new projects should apply the concept of a Responsibility Assignment Matrix (RACI). This makes it clear who is Responsible for doing the work, Accountable for the outcome, Consulted for input and feedback, and Informed on the progress and status. Creating this matrix in advance helps a project avoid confusion and stalling because of lack of alignment.
There are several important patterns with using Asana that you should be aware of: