HashiCorp
HashiCorp

RFC: Standard Communication Tools

An example RFC from HashiCorp for standardizing communication tools

RFC: Standard Communication Tools

SummaryStandardize communication rules and establish common norms of usage
CreatedOctober 17, 2019
StatusWIP | In-Review | Approved | Obsolete
OwnerArmon Dadgar
ContributorsKevin Fishner, Mitchell Hashimoto

Background

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.

Proposal

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:

  1. Zoom. Video conferencing used to have a real-time synchronous conversation.
  2. Slack. Text based chat used to have ephemeral, real-time, asynchronous conversation.
  3. Email. Used to have asynchronous conversations.
  4. Google Docs. Suite of tools for documents, presentations, and spreadsheets and Google Drive for shared access to these files.
  5. Google Calendar. Part of the Google suite, this is the most common way personal and group calendars are managed and shared.
  6. Asana. Project management tool for coordinating work.

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.

Choosing the Right Communication Tool

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.

ToolWhen to use it
ZoomFor real-time, high bandwidth discussions. Should be used for cultivating a discussion rather than transactional asks.
SlackFor real-time, asynchronous discussions. Useful for when team members are online and to have a quick discussion that does not require depth.
EmailFor 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 DocsFor documenting decisions as the source of truth.
AsanaFor 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

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.

Norms and Etiquette

Video chat is fairly intuitive, but there are a few things to be aware of:

  1. Ask before starting to record. Make sure participants provide consent before recording, or make it clear in advance the meeting will be recorded and what the reason is, e.g. to share with others who could not attend.
  2. Mute your audio when not speaking. On calls with many people, this is especially important to avoid distracting background noise. You can set a setting in your Zoom client to mute by default when joining a meeting.
  3. Make an effort to ask people to participate. It can be hard to get into the conversation, especially if people are avoiding talking over one another.
  4. Use video when possible. This allows speakers and listeners to be more engaged and communicate with emotion. Of course there are situations where video might not be feasible, and that's ok.
  5. Default video and audio off. You can configure Zoom in the preferences or settings to disable audio and video when first joining a conference. This is useful to avoid adding background noise when you are just listening and not actively speaking.

Slack

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:

  1. Public Channels. These are channels that anybody can search for and join. These should be used whenever possible to encourage transparency for work related topics and allows anybody to participate.
  2. Private Channels. These are channels that are invite-only. These should be used in smaller settings, where membership may be restricted to team members only or in the case of sensitive information being shared.
  3. Personal Direct Message (DM). This is a conversation with only two people who are directly messaging. It should be used for private communications and when the content is not relevant to a broader audience.
  4. Group Direct Message (DM). This is a conversation with multiple people messaging directly. It is similar to a private channel, but the set of members cannot be changed. Both personal and group direct messages should only be used for very ephemeral purposes to share sensitive information or content not broadly applicable. Private channels are more flexible to handle people changing roles or new people joining, since they can add and remove members.

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:

  1. #talk-X Indicates the channel is meant to chat about X, and is generally not a work related topic. For example, #talk-music.
  2. #proj-X Indicates the channel is meant to collaborate on project X, and is generally organized around a project that has a clear start and end, and so can be archived when the project is over.
  3. #team-X Indicates the channel is meant for members of team X and those who want to collaborate with that team. It is a long lived channel for that team to meet and discuss and for outsiders to listen or engage as well.
  4. #customer-X Indicates the channel is meant for people working with customer X. This can be used to ensure a coordination around that customer and for people to maintain context.
  5. #partner-X Indicates the channel is meant for people working with partner X, similar to the #customer-X prefix.

Norms and Etiquette

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:

  1. Don’t assume all messages are read. Slack is treated as ephemeral, and people are not expected to catch up on all the backscroll and new messages they missed while away. Pretend you are talking in a physical room, and they are not there.
  2. Emotional and physical nuances are lost. Something that may be said in a satirical way is not easily translated to text, where it can be read literally and cause a miscommunication or conflict. 
  3. Emoji are an effective way to communicate emotional context. A message that could be seen as very serious can be interpreted as a joke if the appropriate emoji is used. Learn to use emojis to provide the appropriate context and avoid miscommunications.
  4. Awareness of reach. When you have an in-person conversation, there is a clear audience and end. In Slack, that conversation can linger and people may read it later or chime in. Be aware that you may have a broader communication reach than you intended. Pretend that you are talking in a physical room with all members in the slack channel and determine whether it’s appropriate.
  5. Avoid sensitive topics in large public Slack channels. If you want to discuss a sensitive topic in a smaller forum, or in a live conversation, that is much better suited than a large public channel. This allows you to have sufficient nuance, and avoid a potentially broader reach than you anticipated.
  6. Keep it professional. Make Slack a safe place for everyone to contribute. How we interact in Slack should mirror how we interact in person. Treating people with respect and keeping in line with our Principles are critically important in this space.

Email

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.

Norms and Etiquette

Most people are familiar with Email but there are some internal norms that are important to be aware of:

  1. Use a mailing list for large group emails. If you need to send an email to a group of people regularly, it is better to create a mailing list rather than have a long list of people directly being mailed. 
  2. Keep emails as short and direct as possible. Everybody has lots of email, so be considerate of others in making your message clear and direct.
  3. When a thread has exceeded 6-8 responses, consider other mediums. If an email thread gets very long, it is a good sign that you should use a different medium such as Slack or Zoom.
  4. Capture decisions in Google Docs or knowledge management systems. Do not use email to hold important information such as decisions, plans, or designs. Those are better suited to knowledge management systems that are more easily searched and linked.
  5. Do not reply all on a thread with lots of people. Instead, do a direct reply to the sender or a subset of people that need to be involved. Similarly, if you are sending an email to a large group, put receivers on BCC so that they cannot reply-all.
  6. Configure a send delay. You can configure Gmail (Settings > Undo Send) and other email clients to have a “send delay” which gives you a small grace period to cancel the send. This is useful to fix missing attachments, reply-all, or missing recipients.

Google Docs

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.

Norms and Etiquette

There are several important gotchas with using Google Drive that you should be aware of:

  1. Move documents to be in a team drive. By default, Google Drive creates documents in your personal drive, so they are not easily found later.
  2. Check the permissions on your document. By default, documents have a wide visibility and can be indexed by Google Cloud Search. If your document is sensitive, set the permissions appropriately so only specific users can view it.
  3. Use templates when possible. For common types of documents, proposals, decisions, and designs we often have commonly used templates. This makes it easier to digest and review since information is presented in a standardized way.
  4. Long comment chains are a red flag. Having lots of comments on a document probably indicates the wrong medium is being used. If you find there is a long comment chain, consider using Slack or Zoom to have a more real-time conversation.

Google Calendar

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.

Norms and Etiquette

There are several important gotchas with using Google Calendar that you should be aware of:

  1. Events have public visibility. By default, Google Calendar creates events with public visibility, meaning anybody in the organization can see the event. This is the cultural norm and makes it easier to schedule with people, but for sensitive meetings be sure to set the visibility to private.
  2. Mark times as working hours and out of the office. Make it easier for people to schedule time with you by keeping your calendar up to date. If you set up working hours (Settings > Working Hours) you can mark the hours in your local time zone that you are typically available. This lets others know to not schedule meetings very early or late in your time zone. If you mark days as vacation or out of the office, that also avoids scheduling when unavailable.
  3. Don’t invite yourself to meetings. Events are public visibility by default, so you can see meetings that are scheduled on other people’s calendars. However, that is not an invitation to join a meeting you may be interested in. Just like you wouldn’t walk into a conference room without an invitation, don’t join a virtual meeting. Instead, reach out to the host, express your interest, and ask for an invitation if appropriate.

Asana

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.

Norms and Etiquette

There are several important patterns with using Asana that you should be aware of:

  1. Create templates for common processes. Creating a template of tasks makes it easier to repeat common processes and avoid making mistakes.
  2. Tasks that are not too small or too large. Creating lots of small tasks is annoying for people tracking the project and adds overhead. Creating a single huge task that takes weeks to complete makes the status unclear and can lead to projects that are behind schedule without visibility.
  3. Assign ownership. Ensure tasks have clearly assigned ownership, and consider a RACI matrix. Otherwise tasks can linger for a long time.
  4. Avoid perpetual backlogs. Move tasks that are the perpetual backlog to a different project or out of Asana entirely. These create clutter and an impression of falling forever behind, when they are not high enough priority to be addressed in the short or medium term.