GitLab Handbook: How To Share Knowledge Across Remote Teams

In this article

GitLab, an open source project with more than 2,000 contributors that launched in 2011, is an application that covers all stages of development.

Simply put, it’s a software used to build software. In more complex terms, it’s a way to host your code, run issue trackers, tests and to deploy many different things.

Since it’s initial launch, GitLab has been a fully remote company and to this day doesn’t have a single physical office. The GitLab team contains 300 people operating in 40 countries, all of whom are full-time remote workers.

They started as a company of two people, fully-remote from day one. The co-founders had never even met in person before starting the company and only met a year after they had launched the company together. They grew to 10 people in two years.

Like many startups, they achieved massive growth within a year and ended up with a team of over a hundred people.

Their rapid growth forced the question; how do you unload knowledge from 10 people and make it accessible for a team of over 100, as quickly and easily as possible?

The GitLab team figured out it could be done in two ways.

1. Scaling your Knowledge

Dmitry wanted to take everything he and his current team knew and make it available on a large scale to their new team members and all team members who joined them in the future. All information about how the company runs, its policies, processes and more, should be available to everyone in the company.

2. Preserve your knowledge

If you have only one account manager, and they love the company but you have no idea where your customer’s data is, then you’re in trouble. This fear caused, GitLab to begin documenting everything. Everything from features for their products, company policies and processes, and contribution guides.

They ended up with the GitLab Team Handbook.


What is the GitLab Handbook?

gitlab team handbook

It’s a public webpage, which can be thought of like a Wikipedia for their company.

It’s a central repository for preserving how they run the company. All the information is stored in one place in a single point of truth. It consists of more than 1,000 pages of text that answer virtually any question about the company.

For example, if an employee wants to know how to request a day off, they simply go to the handbook, search “day off” and it gives them all of the instructions on how to take a day off like how to create a calendar event and inform their manager.

Another example of a question is, “Will the company pay for my co-working space?” An employee just needs to search “co-working” in the handbook and they will learn that yes, GitLab will pay for the employees co-working costs.

Even answers to non-company related questions like “How do I move to a different country?” can be found in the Handbook.

GitLab knows their team is all remote and wants to have this information readily available to their team should they face an issue related to this in the future. It aims to answer any question that an employee might have regarding any aspect of their working at GitLab and being a remote worker.


Our Team Handbook is the Wikipedia for the company - Dmitry, GitLab


Everything is always in draft

The idea behind the Handbook is that it is a living, breathing document that is always changing and evolving as the company grows and updates how it operates.

The company has a simple rule regarding how the Handbook gets updated. If something is missing from the Handbook and when you ask a question and receive a response, it’s the employee’s responsibility to add that information to the Handbook.

The employee is tasked with documenting the question and answer in the Handbook and then sending a link to the item in the Handbook to the company Slack channel.

It’s public!

It’s not only readily available for team members, but the general public can access the document freely as well.

This saves them tons of time in the recruiting process because potential candidates can find most information about company policies before even having an interview. Everything from the company hiring process, vacation policy, and what compensation to expect is available in the Handbook.

So when they do go in for an interview, they don’t waste people’s time asking questions to which the answers are available in the Handbook.

Having the information available to the public also increases recruiters attention to candidates who have actually taken the time to read up on the company via the handbook and are only asking questions they could not find the answer to.

People who have done their research already know how the company works and what to expect and won’t be disappointed to learn things they don’t like during the interview process. Having company knowledge publicly available saves the candidate and the company time when hiring.

The Handbook doesn’t give information about what they’ve done in the past or what they’re planning to do in the future. It’s all about what processes and policies are in place right now.

This means that even if there’s a temporary policy, it will be documented in the Handbook until it’s no longer being followed, then it will be removed.

That’s what they mean when they say “it’s always in draft.” It will never be final because it evolves as the company does.


What does the GitLab team think about the Handbook?

gitlab team

“I worked with an external SA candidate last night who had an H1B sponsorship question, and I was able to point him right to the handbook. It was an ideal solution!” – a GitLab Recruiter

In this instance, the interviewer didn’t know the answer right off hand but was able to find the exact section in the Handbook and give it to the interviewee, saving them time both. It also saved the interviewer embarrassment of appearing not to know a specific company policy.

The Handbook saves time and portrays a higher level of company organization than having to fish for answers and get back to candidates the next day.

“If I want to know what all of our engineer repos do, I Google “GitLab engineering repos.” and the first link is to our handbook which has all the information I want.”

This statement came from a GitLab marketer who had some trouble understanding what a certain project does and how they can contact the person responsible for this project. They were directed to a list of GitLab engineering projects and the people responsible for them.

In this instance, the employee just used Google and the GitLab Handbook ranks the highest in a Google search as well.

Another example of a time the Handbook saved the day, is when a candidate wanted to know about the company’s parental leave policy but was afraid of asking the question with the fear that it would deter the company from hiring her. She used the Handbook to find the answer to the question and determine whether or not she is happy with this policy before interviewing.


Q+A With GitLab Co-Founder Dmitriy Zaporozhets



How do you make sure the team handbook doesn’t contain incorrect or out of date information? Are there ‘owners’ for particular areas?

DZ: The Handbook is the general responsibility of everyone but each section should be maintained by the people who edit it and who’s role relates to that specific department or area in the documentation.

For example, if you are an engineering manager, you describe the engineering workflow with labels in the handbook, then before you change the workflow of your team, you must change the documentation in the handbook. Otherwise, the change is not real. Unless it’s in the Handbook, it’s not real.

It’s the people’s responsibility to update the Handbook. If they add something, they’re also usually eager to maintain it and keep the information up to date.

If someone notices that information is out of date or not real, they usually either just change it themselves, propose a change or find the person who made the change. Anyone can use the git repository to see who updated a certain section and contact them directly.

How do you ensure that employees consistently document information into the Handbook?

DZ: Everytime existing employees ask a question in the “Questions” Slack channel, and they get an answer but there is no response with a link to the Handbook, we ping this person to make sure they’ve documented it.

This process scales, because employees want to stay on top of the Handbook, and don’t want to appear to be slacking off in the Slack group where everyone can see.

They are also always reminded of the process when they see anyone else asking a question and forgetting to document it in the Handbook.

What tool does GitLab use to build the Handbook?

DZ: We use GitLab. The Handbook is a git repository itself. Every page in the Handbook has a link at the bottom that says “edit this page.” When you click the link it opens GitLab to the text file in edit mode. So you’re immediately in the web editor in that file.

You make the change, submit the changes and immersion request and that’s how you propose a change. Then you assign it to a relevant person or department.

Are there any sensitive things you’ve decided to exclude from the Handbook?

DZ: We follow this idea that everything is public unless it needs to be private. There are only a few areas that GitLab keeps private.

Salaries, which we consider confidential. Instead we have a compensation calculator which gives prospects a range of what they could earn based on position and seniority, but it’s always a flexible number.

We also don’t share financial information that we are not allowed to share by law or not in the interest of the company. Other than those items, everything else is public.

Does GitLab pay employees based on country or skills or both?

DZ: Both. Our salary calculator is based on three things; rent price in their town of residence, skills, what kind of expertise the position requires. Those three things are considered in the formula to come up with salaries.

Are the remote staff from other countries hired as full-time workers or independent contractors?

DZ: GitLab started as contractors and eventually opened up entities in every country where we have a few employees.

In the beginning, when there was only ten of us, it was difficult to open entities in every country, so the staff operated as contractors. But as soon as we began to grow, we wanted to provide our team with proper benefits so we began opening entities in cities with a concentration of employees.

There are still some people working as contractors, but regardless of the legal status of their employment, our entire team are full-time workers.


You can check out Dmitriy’s talk as well as all the other sessions here: Session Recordings – Running Remote 2018.

Running Remote Conference


Grab your tickets until April 7 before the price goes up.

Don't miss out!

Leave a Reply

Your email address will not be published. Required fields are marked *

Related articles

Discover the valuable insights shared by Ryan Chartrand, an expert in remote team management, as he took the stage at the esteemed Running Remote event. With over 15 years of experience and a strong t…
Discover the valuable insights shared by Ryan Chartrand, an expert in remote team management, as he took the stage at the esteemed Running Remote event. With over 15 years of experience and a strong track record in building brands and products for large-scale companies, he offered his expert predictions for the future of remote work. This blog post summarizes his session, highlighting the key take…
Did you enjoy all the buzz an excitement around Running Remote last April? #RunningRemote took social media by storm, with over 600 mentions and reaching an astounding 1.6 million people in just one m…
Did you enjoy all the buzz an excitement around Running Remote last April? #RunningRemote took social media by storm, with over 600 mentions and reaching an astounding 1.6 million people in just one month. Talk about making waves! But here's the really exciting part: a whopping 65% of our attendees expressed their intention to implement changes within their organizations based on the valuable ins…
Get ready to ignite your remote work success at the Running Remote 2023 Conference, taking place in the stunning city of Lisbon, Portugal on April 25-26! Since its inception in 2018, Running Remote ca…
Get ready to ignite your remote work success at the Running Remote 2023 Conference, taking place in the stunning city of Lisbon, Portugal on April 25-26! Since its inception in 2018, Running Remote captivated thousands of attendees, fostering innovation and collaboration in the remote and hybrid work sphere. If you're planning to join this year's exhilarating experience, we've got some insider tip…

You already purchased this product.