We're an all-remote company that allows people to work from almost anywhere in the world. We hire great people regardless of where they live, but with GitLab team members across more than 60 countries, it's important for us to practice clear communication in ways that help us stay connected and work more efficiently. To accomplish this, we use asynchronous communication as a starting point and stay as open and transparent as we can by communicating through public issues, merge requests, and Slack channels. We also place an emphasis on ensuring that conclusions of offline conversations are written down. When we go back and forth three times, we jump on a synchronous video call.
We communicate respectfully and professionally at all times.
Embracing text communication and learning to use it effectively requires a mental shift. This can feel unusual or even uncomfortable for those who come from a colocated environment, where in-person meetings and vocalized communiques are the norm. Learn more about mastering the use of the written word in an all-remote setting.
If you see something that concerns you in Slack, Issues, Merge Requests, Video, Emails or any other forum, we encourage you to respectfully say something directly to the individual in a 1:1 format. If you are not comfortable reaching out to the individual directly, please reach out to your direct manager or People Business Partner to discuss.
There are 8 key practices to consider during any meeting. They are the following:
Please see our social media guidelines.
It's best practice to start a discussion where possible with a Merge Request (MR) instead of an issue. An MR is associated with a specific change that is proposed and transparent for everyone to review and openly discuss. The nature of MRs facilitate discussions around a proposed solution to a problem that is actionable. An MR is actionable, while an issue will take longer to take action on.
Issues are useful when there isn't a specific code change that is being proposed or needed. For example, you may want to start an issue for tracking progress or for project management purposes that do not pertain to code commits. This can be particularly useful when tracking team tasks and creating issue boards. However it is still important to maintain focus when opening issues by defining a single specific topic of discussion as well as defining the desired outcome that would result in the resolution of the issue. The point is to not keep issues open-ended and to prevent issues from going stale due to lack of resolution. For example, a team member may open an issue to track the progress of a blog post with associated to-do items that need to be completed by a certain date (e.g. first draft, peer review, publish). Once the specific items are completed, the issue can successfully be closed. Below are a few things to remember when creating issues:
Pro Tip: When creating a Merge Request you can add
closes: #[insert issue number here] and when the Merge Request is merged, the issue will automatically close. You can see an example of this here.
Our companywide announcements channel is #company-fyi. It is an announcement only channel, meaning that communications need to be approved via Internal Comms before they can be posted (other than by those who have been given permission, such as E-group members). Please reach out to Internal Communications (@rappleby) to request a #company-fyi announcement. We ask that you make a request at least one week in advance so we can better manage our communications schedule, and that when communicating any significant company changes you should involve Internal Comms from the beginning as part of the planning process.
The above should now all go in the new #whats-happening-at-GitLab channel (formerly the #company-announcement channel)
Below are terms people frequently use when they should use another term. The format is: misused term => correct term, reason why.
Employ multimodal communication to broadcast important decisions. To reach our distributed organization, announce important decisions in the company announcements Slack channel, email the appropriate team email lists, Slack the appropriate channels, and target 1:1s or other important meetings on the same day, with the same information.
We make things public by default because transparency is one of our values.
However it is most important to focus on results. So most things are public unless there is a reason not to. The following items are not public by default:
Information that defaults to not public and to limited access:
Competencies are the Single Source of Truth (SSoT) framework for things we need team members to learn.
In an all-remote organization effective communication is key to exchanging knowledge, ideas, and information. Effective communication at GitLab is: Using asynchronous communication as the starting point and staying as open and transparent as we can by communicating via text through public issues, merge requests, and Slack channels. Placing an emphasis on ensuring that conclusions of offline conversations are written down ensuring a Single Source of Truth and producing Video when necessary.
If you would like to improve your skills or expand your knowledge on topics relating to Communication at GitLab, check out our resources:
Skills and behavior of applying effective communication as a Team Member:
Skills and behavior of applying effective communication as a People Manager:
When taking notes in an agenda, in the handbook, or on our OKRs, keep items numbered so we can refer to Item 3 or 4a. The number is not a signal of the importance or rank of the subject unless explicitly stated to be such. It is just for ease of reference.
In order to effectively communicate an important change to hundreds of distributed employees, we occasionally use an ACK process:
=TEXTJOIN(", ", true, Sheet1!E2:E432)
:ack:and pin to the channel until everyone responds.
@-mention them, if multiple people were working on something try
@-mentioning each person.
Add Values emoji reactions to thank you messages in the
#thanks slack channel
or feel free to use them in GitLab.com, other slack channels and
social media, when you see alignment to our values: GitLab's values.
As a second iteration, we will begin tracking the number of emoji reactions for each value through the Reacji API and update this page with our findings!
When working on a problem or issue, communicate directly with the people you need support from rather than working through reporting lines. Direct communication with the people you need to collaborate with is more efficient than working through your manager, their manager, or another intermediary. Escalate to management if you are not getting the support you need. Remember that everyone is a manager of one and they might have to complete their own assignments and inform the reporting lines.
If there is something that you want to discuss, but you do not feel that it is a reasonable option to discuss with either your manager or CEO, then you can reach out to any of the other C-level GitLab team members or our board member Bruce Armstrong.
Some Topics for Calls:
After GitLab releases a new version on the 22nd of each month, we have a 30-minute call a few days later reflecting on what could have been better:
We spend the first part of the retrospective meeting reviewing the action items from the previous month.
On the 8th of each month (or the next business day), we have a kickoff meeting for the version that will be released in the following month. The product team and other leads will have already had discussions on what should be prioritized for that release. The purpose of this kickoff is to get everyone on the same page and to invite comments.
Both the retrospectives and kickoffs are live streamed to our GitLab Unfiltered YouTube channel and posted to our Unfiltered YouTube channel.
Meetings are incredibly expensive since they require synchronous time. The most common meeting problems can all be address by following the above guidelines around scheduling meetings. Some of the most common meetings problems are outlined below:
|Present instead of Q&A||Pre-record presentations on YouTube, so meetings are only Q&A|
|Meetings are used for brainstorming||People provide thoughtful proposals async|
|No agenda with edit rights for everyone||Ensure that every meeting has an agenda and is available for everyone to edit|
|People are late to meetings or don't have time to use the restroom between meetings||Use Speedy Meetings to give people breathing space before their next meeting|
Indicate your availability by updating your own calendar using Google's "out of office" feature and include the dates you plan to be away in your automated response. Note that this feature will automatically decline any meeting invitations during the time frame you select.
title:"GitLab Videos" source:domain. The script for syncing the files is here.
You are the manager of your attention, and you decide when you do or don't pay attention in a meeting.
You will always have more work than time in your life. If you get invited to a meeting you don't think you should go to, you should decline the meeting. It is better to cancel than to show up and not pay attention.
On the other hand, not every part of a meeting is relevant, but it can sometimes be helpful to have more people in a call. If you only have one discussion point, if possible, try to reorder the meeting agenda to have your point first and then drop from the call. If you get asked a question when you're not paying attention, it is an okay use of time to repeat a question every now and then.
We don't use the first 15 minutes of a meeting to read the materials like they do at Amazon. You can use the start of a meeting to review the materials for the meeting if you need to, given you do not have to be paying attention, but that should not delay the start of the meeting for the people that already have questions based on the materials. Meetings start on time at GitLab.
Don't use your camera to signal you're not paying attention; cameras should always be on.
You should take pride in being the first person to add a question to a meeting agenda, however unlike the First post meme we do want the first post to be more than just "First!". The meeting DRI will be happy to see there is a question ready before to kick off the meeting. The Meeting DRI should remember to thank the person for asking the first question.
In calls that have remote participants everyone should use have their own equipment (camera, headset, screen).
When multiple people share equipment the following problems arise for remote participants:
The people sharing equipment also have problems because they don't have their own equipment:
The disadvantages for remote people are much greater than for the sharing people and hard to notice for the sharing people. The disadvantages cause previously remote participants to travel to the meeting to be in person for a better experience. The extra travel is inefficient since it is time consuming, expensive, bad for the environment, and unhealthy.
Theoretically you can have multiple people in a room with their own equipment but in practice it is much better to be in separate rooms:
*.md text eol=lfis set in the repository's
git config --global core.autocrlf inputon your client.
Zoom Link [Link]. Rather, paste the full link directly following the word
Zoom. This makes the link more prominent and makes it easier to follow while viewing the document.
yyyy-mm-dd, for example 2015-04-13, and never 04-13-2015, 13-04-2015, 2015/04/13, nor April 13, 2015. 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 2018-01 for January. Refer to a year with CY18 (never with 2018) and a quarter with CY18-Q1 to prevent confusion with fiscal years and quarters.
9:00 PT. It isn't often necessary to specify whether a timezone is currently observing Daylight Saving Time, and such references are often incorrect, so prefer "PT" to "PDT" or "PST" unless you have a specific need to differentiate between PDT and PST.
##in Markdown, "Heading 2" in Google Docs); start at the second header level because header level 1 is for titles. Do not end headers with a colon. Do not use emoji in headers as these cause links to have strange characters.
merge request (MR).
Many times an explanation can be aided by a visual. Whenever presenting a diagram, we should still allow everyone to contribute. Where possible, take advantage of the handbook's support for Mermaid. If you are new to using Mermaid or need help troubleshooting errors in your Mermaid code, the Mermaid Live Editor can be a helpful tool. Where taking advantage of Mermaid isn't possible, link to the original in our Google Drive so that the diagram can be edited by anyone.
Mandel Communications refers to SCI-PAB® at the "surefire, six-step method for starting any conversation or presentation." When you only have a few minutes to present your case or grab your listener's attention, this six-step process can help you communicate better and faster.
Example - The Management team asking for time to resolve a problem
Some examples can be found at SCI-PAB - Six Steps To Reach Your Audience.
If you need to provide the details of GitLab's contact information you can take the address from the visiting page for reference; or the mailing address of the office in the Netherlands if that is more applicable.
If a phone number is required, leave this field empty by default. If that is not possible, then use the general number (+1-415-761-1791), but be aware that this number simply guides to a voice message that refers the caller back to contacting us via email.
There are two types of code names:
At GitLab we use ubiquitous language to increase communication efficiency.
This is defined in Domain-driven design as: "A language structured around the domain model and used by all team members to connect all the activities of the team with the software."
We use it for activities in GitLab, even ones not implemented in software.
By having ubiquitous words to identify concepts we prevent confusion over what is meant, for example we refer to parts of our organization as a function, department, or group depending on exactly what is meant.
If a term is ambiguous don't use it, for example our hiring definitions have roles and vacancies but avoid the ambiguous word job.
Make sure that people can infer as much as possible from the word, for example our subscription options allow you to know if someone if using self-managed or GitLab.com.
Make sure terms don't overlap without clearly defining how and why, for example see our tier definitions.
Keep terms to one or at most two words to prevent people from introducing ambiguity by shortening a term. When using two words make the first word unique because people tend to drop the second word more often.
MECEFU is an acronym for Mutually Exclusive Collectively Exhaustive Few words Ubiquitous-language.
You pronounce it: MessiFu. Think of the great soccer player Lionel Messi and his kung fu or soccer fu skills.
We want to use MECEFU terms to describe a domain to ensure efficient communication. MECEFU terms have 4 characteristics that help with efficiency:
An example of a MECEFU term is our sales segmentation:
One nit-pick is that the Medium of SMB and Mid of Mid-Market sound very similar.
Simple Language is meant to encourage everyone at GitLab to simplify the language we use. We should always use the most clear, straightfoward, and meaningful words possible in every conversation. Avoid using "fluff" words, jargon, or "corporate-speak" phrases that don't add value.
When you don't use Simple Language, you:
When you do use Simple Language, you:
Here's an example:
We're now launching an optimization of our approach leveraging key learnings from the project's postmortem.
A Simple Language sentence
We're creating a new plan based on what we learned from this project.
Simple Language is important both when we're speaking to other team members and when we're representing GitLab to people outside the company.
Be sure to use Simple Language in written communications as well. Our handbook, website, docs, marketing materials, and candidate or customer emails should be clear, concise, and effective. Corporate marketing maintains guidelines on GitLab's tone of voice.
|Getting buy-in/Getting alignment||Asking for feedback since DRIs make decisions|
|Get all your ducks in a row||Be organized|
|Don't let the grass grow too long||Work quickly|
|Leverage||Use more explicit phrasing- debt, etc.|
|Send it over the wall||Share it with a customer|
|Boil the ocean||Waste time|
|Punt||Make less of a priority|
|Helicopter view/100 foot view||A broad view of the business|
|Turtles all the way down||Cascade through the organization|
For example, do not suggest that you're "working in real-time" when a matter is in disarray. Convey that a lack of organization is hampering a result, and provide feedback and clear steps on resolving.
Do not use a cool term such as "tiger team" when the existing term of "working group" is more exact. While cool terms such as these may be useful for persuading colleagues to join you in working towards a solution, the right way isn't to use flowery language.
The last example is when we used 'Prioritizing for Global Optimization' for what we now call a headcount reset. When we renamed it we saw a good reduction in the use of this disruptive practice of moving people around.
As GitLab continues to grow, sharing knowledge across the community becomes even more important. The Deep Dives page describes initiatives we are trying to encourage this. This aligns with how we work since everything at GitLab is public by default.
– specific comms tools
Slack is to be used for informal communication only. Only 90 days of activity will be retained. Accordingly, Slack should specifically NOT be used for:
Internal slack messages between team members are still considered professional communication. Please do not use or add emoji's to slack that are of a political, religious or of a sexual nature. You can refer to the Religion and politics at work section of the handbook. When in doubt do not use or add the emoji. If you have any concerns about an emoji that was used, please reach out to the author or if you are not comfortable doing so please reach out to your People Business Partner.
Note: We don't use the term private message, because these direct messages are not inherently private like a phone call or private letter. The messages are potentially accessible by Workspace admins or via Backups. Slack refers to these types of messages as direct messages themselves.
Thanks for reaching out, that's a great question/idea 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 direct messages](/handbook/communication/#avoid-direct-messages)
@Person asked "question" in a DM, pulling that out here if anyone else has input.
Please consider posting in a public channel before direct messaging
Why direct message me when you can post in a public channel?
Use private channels instead of group direct messages. Group direct messages are very hard to maintain, track and respond to. First, consider whether the conversation can take place in a public channel. If not, please use a private channel instead.
For all the same reasons that we want to avoid direct messages, use public channels, and be handbook-first, we track the % of messages that are not DMs. As we grow headcount, we exponentially increase the lines of communication- 3 people have 3 communication lines, 4 have 6, and 41 have 820. As a result, there is a natural tendency for people to prefer private channels of communication. The intentions are good, as people are looking to reduce noise for others, but this can lead to the same problems as described elsewhere on this page, notably:
Slack is our primary source of chat communication and is where many personal interactions happen. We want to continue to encourage folks to build personal relationships with one another which will often happen over DMs.
We know that DMs will always exist. We don't want to eliminate them. We set a target of Slack DMs to consist of less than 50% of messages. At the time that we set this target, it is about 80% of communications.
Everything at GitLab is a work in progress, so if we see a culture shift where Slack is not where work is occurring, thus inflating the amount of communication that is personal that is occurring, we can always change this KPI, but the steady growth of Slack messages paralleling the number of team members does not seem to suggest that is the case.
The previous KPI (% of messages sent in public channels) was about public channels but since some necessary parts of the business occur in private channels (discussions around comp, hiring, recruiting- and we do A LOT of hiring), this version of the KPI makes more sense. Earlier in our history, 50% of all communication was in public channels.
@-mentioning the team.
@mentiona specific team (Slack User Group), consider the size of the group you are mentioning (see group membership) and the impact of pinging all of these people for the particular situation. If something is urgent and important:
@hereto notify all currently active members in the room. Please only use
@hereif the message is important and urgent.
@channelto notify ALL members in the room, irrespective of away status. Please only use
@channelif the message is important and urgent.
:white_check_mark:emoji or similar to indicate an inquiry has been answered. Anyone can add the emoji. If you're not sure, then feel free to leave it up to the person who asked. An emoji indicator is particularly helpful in channels where lots of questions are posted, such as
Preferences > Notifications > When I'm not active on desktop...and "send me email notifications."
(internal)after the link. For example: https://gitlab.slack.com/archives/C0AR2KW4B/p1555347101079800 (internal)
To get in touch with the e-group on Slack, you can use the following channels. When in doubt, you can use the general
#e-group channel to reach out to the entire group.
|VP of Product||
|VP of Product Strategy||
|EVP of Engineering||
The alphabetically sorted starter list below spotlights a few of GitLab's many Slack channels in an effort to provide guidance to team members regarding the best places to ask specific questions and/or engage in discussion on a variety of topics. See Slack's Help Center for instructions on browsing all available channels.
Learn more in our Chat handbook section.
||Official company announcements, restricted permission levels to ensure high-signal; all GitLab team members are automatically added to this channel.|
||Open to posts from all team members including reminders, events, project updates, etc.; all GitLab team members are automatically added to this channel.|
||Stay up to date on GitLab’s latest Diversity, Inclusion and Belonging initiatives and share feedback and thoughts about how we can make our environment even more inclusive.|
||For questions pertaining to expenses (e.g. Expensify).|
||Specific questions about using Git in the terminal.|
||Cute kid photos, tips on getting your children ready for school, etc.|
||Get help in finding existing issues for existing problems.|
||Create a Help Request in this channel should you have any IT general questions or trouble with setup (e.g. 2FA, accounts, etc.).|
||Search loc_insert your location to connect with GitLab team members in your location (e.g
||For any questions regarding merge requests.|
||For new GitLab team members to introduce themselves to the company and for existing team members to share updates with new hires.|
||GitLab is an all-remote organization. Where’s your office today? Share a photo or use words to describe it.|
||For questions pertaining to payroll and contractor invoices (e.g. ADP, etc.).|
||For general People Ops questions (e.g. onboarding, offboarding, team meetings, etc.).|
||For any general help with anything, really, and Git. If you have a question but you're not sure in which channel you should ask it, questions is always a great place!|
||Anything and everything from photos, news, food, music, etc.|
||For questions about referrals, the hiring process, and/or candidate status.|
||To share news, thoughts, feedback and anything else pertaining to remote work! Learn more about GitLab's approach to remote work.|
||To stay updated on transitions/promotions, new GitLab team members joining, work anniversaries, etc.|
||Recognition is an important part of GitLab's culture; give a public "thanks" to your teammates here!|
||For anything related to compensation, benefits, or equity. You can also check out the Total Rewards issue tracker and handbook page!|
||A place to discuss all things travel!|
||Employee resource group for members and allies.|
We upgraded tiers to improve efficiency and security with the ability to use Okta to login into Slack. This will help us scale by improving provisioning and deprovisioning of our corporate systems. This upgrade will also allow us to improve the auditing requirements where identity management is in scope. The Plus tier also includes announcement only channels, 99.99% guaranteed up time, 24x7 support with guaranteed response in four hours or less, and the ability of Corporate Export.
The times this feature would be used would be to comply with certain obligations. Corporate Export must be enabled by Slack in accordance with Slack’s policy, which can be found here.
Examples of instances where GitLab may need to use this feature may include, but are not limited to, those situations listed in Slack’s documentation.
Slack is the business-provided internal communications tool to use for collaboration and connecting with team members. Please keep GitLab values in mind when communicating directly with other team members. If you have a confidential personal issue that you do not feel comfortable discussing via a business-provided internal communications tool, it is recommended to use a personal form of communication such as a text message or phone call. For additional questions, please address in the issue.
GitLab has choosen to restrict the ability to install apps, and we have a process to approve or restrict certain apps for our workspace. In order to add a new app to Slack, you need to create a vendor approval issue. Once that's approved by all parties, please request approval to add the app to Slack following the steps below:
Please note that this is only required for new apps that have not been reviewed or approved. If your request is to add a new process or update an existing process for how an application works in slack, please refer to our Business Technology Change Management process.
Use the "Slack Down!" group chat on Zoom.
Once service is restored, go back to Slack.
Use Slack calls.
/callto trigger a call.
Once service is restored, go back to Zoom.
Join the Slack Down! room on Hangouts Chat. Once service is restored, go back to Slack and Zoom.
Never use a Google Doc / Presentations for something non-confidential that has to end up on the website or the handbook. Work on these edits via commits to a merge request. Then link to the merge request or diff to present the change to people. This prevents a duplication of effort and/or an out of date handbook.
If you do need a Google Doc, create one with your company G Suite (formerly Google Apps) account and set the visibility and access controls according to the following guidelines:
|Visibility Setting||Use Cases|
|On - Public on the web||If you want the document to be discoverable by anyone on the internet.|
|On - Anyone with the link||Avoid this setting. Instead, choose On - GitLab, then explicitly share the document with desired external individuals. Only use this if you want the document to be public but not indexed by Google.|
|On - GitLab (Recommended Default)||This is the recommended default as it allows anyone within GitLab to easily discover documents via searching for their name within Drive.|
|On - Anyone at GitLab with the link||Avoid this option as it limits discoverability by others at GitLab.|
|Off - Specific people||When the document contains highly sensitive or private information such as 1:1s with direct reports|
|Access Setting||Use Cases|
|Can Edit||Anyone that can view the document can edit it. This is the recommended setting when On - GitLab is enabled for the document|
|Can Comment||Anyone that can view the document can add a comment but cannot edit the document. This is ideal if you want to provide visibility but retain more fine-grained control of document editing.|
|View||Individuals with access to the document will only be able to view it.|
The recommended defaults when sharing a document for GitLab internal purposes is setting visibility to On - GitLab and access to Can Edit. Reference Google's documentation on Link Sharing to learn more.
GitLab uses Zoom for video communications.
Please visit the Tools and Tips handbook for Zoom usage guidelines.
COVID-19 is impacting how team members connect and communicate with family.
Due to school closures, parents are tasked with being responsible for their children while at home. Family and friends first, work second is an important Diversity, Inclusion & Belonging sub-value. To that end, we are encouraging GitLab team members to allow their children to connect with other children around the world.
During this time of physical distancing, GitLab team members are welcome to use Zoom to connect with family if other options like FaceTime, etc. are not an option. Please ensure that attendees who are not GitLab team members have their own Zoom account. To ensure GitLab does not incur toll charges, please use Internet-based voice when possible.
Please visit a detailed guide covering everything you need to know about hosting or participating in a GitLab webinar.
We recommend you set your Google Calendar access permissions to 'Make available for GitLab - See all event details'. Consider marking the following appointments as 'Private':
There are several benefits and reasons to sharing your calendar with everyone at GitLab:
Due to our timezone differences, there are small windows of time where our availabilities overlap. If other members need to schedule a new meeting, seeing the details of recurring meetings (such as 1-1s) will allow for more flexibility in scheduling without needing to wait for a confirmation from the team member. This speaks to our value to be more efficient.
If you add blocks of time spent on recurring tasks to your Google Calendar to remind yourself to do things (e.g. "Check Google Analytics"), consider marking yourself "Free" for those events so that coworkers know they may schedule a meeting during that time if they can't find another convenient time.
See the YouTube page for options and instructions for posting recordings and live streaming to our YouTube channels.
Anyone can become certified in GitLab Communication. To obtain certification, you will need to complete this quiz and earn at least an 80%. Once the quiz has been passed, you will receive an email with your certification that you can share on your personal LinkedIn or Twitter pages. If you have questions, please reach out to our L&D team at