We’re an all-remote company, with teammates from all around the world and (soon) 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:
- sourcegraph/sourcegraph repository
- sourcegraph/about repository
- Project roadmap
- Issue tracker
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 decisions or changes resulting from these places need to be reflected in a source of truth:
- Company meeting (Mondays 10:30-11:00am PST/PDT)
- Always start on time, even if some participants are late. (And try not to be late.) Latecomers can watch the Zoom recording.
- 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.
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).
See “1-1 meetings”.
We use Google Docs for:
- Collaborative editing of ephemeral documents
Deprecating a Google Doc
Deprecate a Google Doc when 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.
- Rename the Google Doc to
DEPRECATED - <previous doc title>.
- Delete all doc content, and replace it with
See <URL to new content location>..
We use Slack for team chat, which means ephemeral conversations. To enforce this, only 90 days of Slack activity in public channels is retained. Any important decisions or changes need to be reflected in the source of truth.
- Common channels
- Historical archive of Slack messages prior to 2019-11-09: unzip and open
sourcegraph-slack-archive-to-20191109/index.htmlto view. If you consult this, please be sure to add whatever information you learn to a source of truth so we reduce our reliance on this archive.
Avoid private messages
- When using Slack for work-related purposes, avoid private messages. Private messages discourage collaboration. You might actually be contacting the wrong person, and they cannot easily redirect you to the right person. If the person is unavailable at the moment, it is less efficient because other people can’t jump in and help. Use a public channel and mention the person or group you want to reach. This ensures it is easy for other people to chime in, involve other people if needed, and learn from whatever is discussed.
- If someone sends you a work-related private message, it is OK to let them know you’d like to take the conversation to a public channel, linking to this section of the handbook. The process might look something like:
- In the private message:
Thanks for reaching out. That’s a great question/idea that I think the rest of the team could benefit from. I’m going to move this to #public-channel based on our desire to avoid private messages.
- In the appropriate public channel:
@person asked "question" in a DM, pulling that out here if anyone else has input.
- Answer the question in a thread on that channel message, allowing others to benefit.
- If you must send a work-related private message, don’t start a conversation with “Hi” or “Hey” because that interrupts their work without communicating anything. If you have a quick question, just ask the question directly, and the person will respond asynchronously. If you truly need to have a synchronous communication, then start by asking for that explicitly, while mentioning the subject. For example: “I’m having trouble understanding issue XYZ. Can we talk about it quickly?”.
Most meetings at Sourcegraph are video calls. We prefer Zoom for all video calls because it seems to have the best connectivity and compatibility.
- Google Calendar has a Zoom plugin where you can easily add a Zoom link for a video call to the invite.
- 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.
- Always use ISO dates in all writing and legal documents because other formats lead to online confusion. Use
yyyy-mm-dd, for example 2020-04-13, and never 04-13-2020, 13-04-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 2020-01 for January 2020.