Communication

We’re an all-remote company, with teammates from all around the world and no primary office. To make this work, we need to be deliberate about how we communicate.

Sources of truth

These places are the source of truth for information at Sourcegraph. Information in these places is expected to be accurate and up-to-date:

Scratchpads and ephemeral information (non-sources of truth)

The following places are not sources of truth. Treat documents and conversations in these places as “scratchpads” or documents that were true at creation time but aren’t expected to be up-to-date. Any changes resulting from these places need to be reflected in a source of truth:

Meetings

Internal meetings

  • Always start on time, even if some participants are late. (And try not to be late.) Latecomers can watch the Zoom recording to see what they missed.
    • Don’t punish the people who arrived on time by waiting for people or repeating what was already said.
    • If the meeting’s leader is not present at the precise start time (and hasn’t proactively mentioned they are late), everyone should leave the call and switch to other work. This is a nudge to respect others’ time and to not be late to meetings you lead.
  • Always end on time (or early).
    • If there’s more to discuss, handle it asynchronously or schedule a new meeting with the appropriate participants.
    • A meeting that would run over is a nudge that the meeting’s agenda or duration was wrong, or that the meeting was led ineffectively.
  • Remind people of your role in cross-functional meetings (including company meeting) or any other meeting that has team members you haven’t met yet. We’re growing, and it’s hard to remember everyone’s role! (The org chart helps.)

Scheduling meetings with Google Calendar

Before you start, please make sure you’ve configured your Google Calendar settings as described in the onboarding guidelines.

  • When creating the Google Calendar event:
    • Use the “Find a Time” feature to see when you and other meeting attendees are all available.
    • Add a Zoom video call.
    • Add a Google Doc link to the event description for taking notes during the meeting.
      • If the meeting is recurring, use the same Google Doc for all meetings.

Structured meetings

You may try this approach for more effective meetings. The goals are to surface more topics to discuss (instead of just whatever topics people remember during the meeting) and spend more time on informed discussion (instead of conveying information, which is usually better done in writing).

This assumes that currently the meeting has a Google Doc with notes that people sometimes write in advance and sometimes don’t. This is better than nothing, but we can do even better.

  1. Everyone uses the first 5–15 minutes of the meeting to write down what they would like to communicate (e.g., updates on their progress, topics they would like to discuss, problems they’ve encountered, etc.). Then the rest is discussing and deciding in order.
    • Use this for a few weeks, and then…
  2. Everyone writes down their items before the meeting. A topic that isn’t written down can’t be discussed. Spend the first 5 minutes of the meeting reading what other people wrote down, then discussing and deciding in order.
    • Use this for a few weeks, and then…
  3. Everyone writes down their items by a certain time before the meeting (e.g., 12 hours before). Everyone reviews what other people wrote before the meeting starts. Only people who have commented on an item can make further comments on the topic during the discussion.

This idea is from The Great CEO Within (Chapter 12) by @mattmochary.

Structured meetings are great, but it’s important to have casual, unscheduled, free-flowing time to chat with people as well. That helps build personal bonds and surface topics or ideas that might not come up in structured meetings.

External meetings

  • Join meetings early or on time.
  • End meetings on time.
  • Be patient for external folks who are running late to our meetings.
    • For customers, prospects, and users, wait on the line for at least 10 minutes (and send them a friendly reminder after 3–5 minutes).

Video calls

Most meetings at Sourcegraph are video calls. We prefer Zoom for all video calls because it seems to have the best connectivity and compatibility.

  1. Google Calendar has a Zoom plugin where you can easily add a Zoom link for a video call to the invite.
  2. Be sure to include the Zoom dial-in for team members who need to join by phone. (If you use the Zoom plugin linked above, this is automatic.)
  3. In your Zoom settings, enable “Join before host”. (It is enabled by default in our Zoom organization account, but you may have overridden it previously.) This lets the meeting get started even if you aren’t there.
  4. Set Zoom meetings to be recorded to the cloud so that you and other teammates can refer back to them later.
    • If any participant doesn’t feel comfortable with the meeting being recorded, it is fine to not record it.
    • All Zoom recordings saved to the cloud are deleted automatically after 30 days. Deleted Zoom recordings will be placed in the meeting host’s trash for an additional 30 days. After this time the recordings will be permanently deleted.
    • Due to issues of privacy and compliance, Zoom recordings should only be downloaded and kept beyond 30 days if there is an explicit business use for doing so.
    • In the event that you need to download and store Zoom recordings Sourcegraph’s Google Drive should be used as the default location.

1-1 meetings

See 1-1 meetings.

Announcements

See Announcements.

Don’t use URL shorteners

Do not use URL shorteners (not even ones that we pay for or that use a custom domain). Devs don’t like or trust them.

Google Docs

  1. We use Google Docs for:
    • RFCs
    • Collaborative editing of ephemeral documents
  2. The shared Sourcegraph Drive folder on Google Drive is visible and editable by all Sourcegraph team members.
    • To share a doc with team members, move it to this folder.
    • Don’t worry about putting your doc in the right folder. If you want to use folders, you can. But we’ve given up on trying to impose a folder structure company-wide on our Google Docs, and we just rely on links and search to find Google Docs.

Deprecating a Google Doc

Deprecate a Google Doc when all of its content is added to the handbook, blog, or documentation (or other source of truth). This lets people know to not consult, edit, or comment on it anymore.

  1. Rename the Google Doc to DEPRECATED - <previous doc title>.
  2. Delete all doc content, and replace it with See <URL to new content location>..

See example of deprecated Google Doc.

If you need to deprecate just part of a Google Doc, replace the deprecated portion with DEPRECATED: See <URL to new content location>.

Writing

  1. Always use ISO dates in all writing and legal documents because other formats lead to online confusion. Use yyyy-mm-dd, for example , and never -2020, -2020, 2020/04/13, nor April 13, 2020. Even if you use an unambiguous alternative format, it is still harder to search for a date, sort on a date, and for other team members to know we use the ISO standard. For months use yyyy-mm, so for January 2020.
  2. When referring to a fiscal year, prefix the year with FY (e.g., for fiscal year 2021). Sourcegraph’s fiscal year starts on February 1 and ends January 31. {#fiscal-year} Note that fiscal years that don’t align with calendar years (such as our fiscal year) are referred to by the year in which the period ends (so refers to February 1, 2020 through January 31, 2021). Learn more about fiscal years.
  • FY__ (e.g., is fiscal year 2021, which means through )
  • FY__- (e.g., FY21-Q1) is February 1 through April 30
  • FY__- is May 1 through July 31
  • FY__- is August 1 through October 31
  • FY__- is November 1 through January 31

Seeking and giving feedback

Handling conflicts

Brain Food

Brain Food meetings are our internal knowledge sharing sessions. These meetings can be formal presentations or informal discussions and are open to anyone in the company. Subjects of talks are completely free and are not limited to tech discussions. Here are a few examples:

  • Sharing internal team knowledge to the rest of the company
  • Presenting a useful tool
  • Presenting a personal project
  • Hands on session / workshops
  • Brainstorming session about an experimental subject
  • Preparing an external talk

If you have an idea for a session, add an event to the calendar and invite the engineering-team@sourcegraph.com