Learning Documentation Techniques for Scaling Organizations from the "GitLab Handbook"
A documentation culture is necessary for a healthy, scaling organization
It is extremely important to leave behind and utilize documentation/writing within an organization. Having high-quality documentation allows information to circulate throughout the organization and ensures transparency. Because you don't need to explain things verbally every time to circulate information, it becomes easier to scale even when the number of members increases. Since past conclusions become accessible, it leads to building upon discussions and improving the quality of decision-making. In the first place, reading something allows for a higher volume of processing per unit of time than listening to someone explain it, and it can be done asynchronously. Accumulating good documentation as an asset within a company is essential for the growth of not just startups, but every kind of organization.
However, on the other hand, it seems that not many companies have successfully established a high-quality documentation culture. For example, it is common to hear about companies introducing an internal Wiki as a place to accumulate internal documentation. However, in reality, because that Wiki is driven only by the energy of a small number of maintainers, the information often gradually becomes outdated and ends up becoming a mere shell.
The opposite also happens. Even if information is formally accumulated, not many companies organize, manage, and utilize it in daily decision-making. Documentation work that is not correctly utilized degrades into mere formality, and ends up being ridiculed as bureaucratic red tape or work for the sake of work.
In the midst of this, I have discovered a company where the documentation culture is insanely thorough, so I would like to introduce it. That company is a startup called GitLab. GitLab is a Git repository hosting service similar to GitHub.
The characteristics of GitLab are: 1) over 1,000 employees are scattered all over the world, working fully remotely, and 2) they value openness to a cult-like degree.
For example, even incident response is fully remote and open. In 2017, there was a massive outage where GitLab's database was destroyed, and even then, various engineers were responding fully remotely. And, the situation was actually being streamed live on YouTube (which is insane!).
At GitLab, a highly developed documentation culture exists so that people can work productively even while working remotely. Since the product GitLab makes is also a development collaboration tool, this also has an aspect of dogfooding.
Anyway, the documentation called the GitLab Handbook is insane, so I want you to take a look at it.
This company manages the group of documents necessary for company operations in a single Git repository in the form of the "GitLab Handbook". First, before I say anything else, I want you to take a look at this vast amount of documentation.
If you browse around a bit, I think you will be able to feel the unimaginable size of this document collection, the amount of wisdom packed into it, the obsessively detailed descriptions of processes, and the cult-like ideology that supports this documentation culture.
The update frequency is also tremendous; you can see it from the update history, and you can see that a large number of commits are reflected every day. As for the total size of the documents, it reaches 1.67 million words, which is about 3,705 pages.
This documentation is truly a treasure trove of learning, so I strongly recommend that startup managers and others look at various pages. I don't think there are many examples where the best practices of a successful startup company are made this detailed and open. However, I think there are people who don't know where to start looking, so I would like to introduce three highlights here.
Communication: Guidelines and practical methods for internal communication
In a distributed organization that does not have a physical office, communication becomes a challenge. This page comprehensively describes how internal communication should be, from the concept level to the concrete practice level.
Below are my personal learning points.
・It seems they ensure Slack only retains 90 days of activity. A bold arrangement to not use/allow use for actions such as documenting decisions, official records, or obtaining approvals (It seems that at GitLab, ongoing work is done on GitLab, and there is no arrangement where work is done on Slack)・They encourage not using private messages, and if you use a private message, they explicitly state to copy and paste this text in the DM -> "Thanks for reaching out! Someone on the team might find this question or idea useful, so I'm going to move this to a public channel"・And they explicitly state to say this text in the public channel you moved to: "@Person asked me a question in a DM, so I'm writing it here so everyone's opinions can be reflected"・If you still get a lot of private messages, set your Slack status to a prominent emoji and set it to "Why are you DMing me instead of using a public channel?"・Don't just write "Hello" and send it. Only ask the direct question.・The starter list for Slack public channels is organized・There is a channel to upload photos of your children・There is a #questions channel for things where you don't know which channel to ask in・Openly express gratitude to teammates in the #thanks channel・When Slack is down, a backup Zoom group chat called "Slack Down!" is prepared・When Slack and Zoom are down, a Hangouts chat room is prepared・They match the 7 GitLab Values with stamps
・Video chat meetings start on time, don't wait for people, and it's okay to cut them off when the time is up・Always keep the video ON during video chats・Actively let children and pets appear on screen during video chats (This is the opposite of what one might imagine and is interesting; perhaps it means that in remote work, you have to actively create opportunities for casual conversation)・Consider using Shush (a tool that allows you to mute the microphone with a hotkey) during video chats. (Does this mean you switch ON/OFF a lot?)・If there is background noise, encourage all participants to mute their microphones・Don't say "Can everyone hear me?", start with the main topic (Participants will speak up only if they cannot hear, so there is no need to confirm that)
Global Compensation: An Open Approach to Salary Determination
Evaluation and compensation are critical issues in any organization, but GitLab maintains a high level of openness even regarding these sensitive matters. You can learn about their philosophy and specific practices from the page mentioned above.
Below are my personal takeaways in bullet points:
・The compensation formula is extremely simple and clear: Your compensation = SF benchmark x Location Factor x Level Factor x Compa Ratio x Contract Factor x Exchange Rate
・The SF benchmark level is based on San Francisco salary levels and is determined based on various survey data
・The SF Benchmark value is managed in this yml file
・The SF Benchmark is updated annually
・The benchmark is adjusted to position it at the 50th percentile of the industry
・If more than 20% of people decline offers due to salary levels, the benchmark is adjusted
・The Location factor is determined by comparing compensation levels with San Francisco. It is calculated as the average of three data points (there is also a lot of explanation about how to calculate it)
・By the way, the Japan Location Factor is apparently 56.3 against SF's 100 (though I feel Tokyo might be higher)
・Looking at things like this, I get the impression that HR work is truly about serious economic data research and statistical analysis
・In other words, if you move, your salary changes
・The reason for different salary levels by region is to prevent members from concentrating in low-wage areas if the salary level were the same. If the wage level were the same, it would not be possible to create many jobs.
・There seems to have been a lot of discussion about this, and the reasons are explained in detail in a Blog Post (Why GitLab pays local rates)
・The Level factor has 7 levels: 3 for members, 2 for managers, and 2 for directors
・These job levels also differ slightly by role, but they are managed in the yml file under the git repository
・The Compa ratio is a lever held by the direct manager, allowing them to adjust within a 30% range from -15% to +15% based on performance
・The Contract Factor is due to the difference between employees and contractors; for contractors, it is multiplied by 1.17. This is because they have to pay for social insurance, etc., themselves. Also, in some countries, due to legal regulations, they can only be hired as contractors
・The annual compensation review process includes a market environment review. I think it's interesting that salaries are adjusted due to macro factors even if nothing else changes
・I personally find the model very convincing: not being too swayed by previous salary levels, keeping a close watch on the labor market, and maintaining competitiveness at the top xx percentile level. It makes it harder to be economically overvalued or undervalued.
Onboarding Process: A Standardized New Employee Onboarding Process
At GitLab, the member onboarding process is also very refined. For example, there is a long list of things to do in the first month.
Below are my personal takeaways:
・Set up five 30-minute calls with five colleagues in the first week to talk about GitLab's team and culture
・The onboarding team involves the manager, a buddy, and the People Experience team
・They specify someone who is in the same time zone as the new employee and has been at GitLab for at least three months
・To maintain security even in remote locations, they have you share a screenshot showing that Mac's FileVault HDD encryption is enabled
・They use 1Password
・They use Okta for SSO
・They have you update your LinkedIn and include your position title correctly
・Joining the #donut-be-strangers channel sets up a random coffee break call once a week
・They tell you to follow GitLab's LinkedIn, Twitter, Facebook, and YouTube
・They have you fill out an Onboarding NPS survey when the first 30 days have passed
・They have you leave a review on Glassdoor or Comparably when 30 days have passed (an employee-side review site for companies, similar to Tenshoku Kaigi in Japan). I thought it was reasonable to encourage adding data to job-related sites when you think about it
・There is a GitLab Quiz about the product, and the manager tests whether the new hire understands the product correctly
・Avatars used for icons, etc., are made using Gravatar
・They make you set up your profile for Slack, GCal, Zoom, etc., very thoroughly
・Various articles, including external and internal resources, are posted, and they are summarized with instructions to "read this"
---
That is all for the three areas I introduced. There are many other pages, so please take a look. I recommend starting from your own job function or what you are currently working on or discussing, and tracing how it is handled by GitLab's practices. You will often run into various hints.
What points can Japanese startups adopt?
What points can we imitate, and what practices can we adopt? GitLab is a global, reasonably large organization (1,186 team members) and a distributed company, so I think there are many points that would not work well if Japanese startups imitated them exactly. However, I still feel there are many points to learn from.
The page above summarized several points for handbook operation, so I would like to list three parts that seem imitable.
1. Understand that a Wiki is not enough and you cannot scale without a Git repository
Company handbooks often start as Wikis, which are excellent in terms of ease of getting started, but they tend to become outdated over time.
With a Wiki, you cannot make proposals that span multiple parts of a page or multiple pages. Also, you cannot separate the roles of the worker and the reviewer. Furthermore, you cannot discuss whether or not to incorporate a proposal. As a result, the handbook falls into a state where it cannot be refactored.
By using a distributed version control system called a Git repository, this problem can be solved. Anyone on the team can make proposals, and the manager who manages the relevant section can make decisions on approval. Open discussions can also take place within a Pull Request.
Also, when they want to edit content while everyone is looking at it during a meeting, they seem to use Google Docs, and once the meeting is over, they summarize the content into a Merge Request (a Pull Request in GitHub).
2. Stick to the Handbook-First philosophy
At GitLab, they stick to the Handbook-First philosophy. The handbook is always up to date and written so that there is no duplication within it. It is maintained to have what is known as a Single Source of Truth. Therefore, situations often seen in Wikis, where multiple documents point to the same content and contradict each other, no longer occur.
When having various discussions on Slack, email, or internal presentations, it is encouraged to always try to attach a reference URL to the relevant handbook. Instead of going out of your way to create presentation slides when explaining something, it is encouraged to use the handbook as a substitute.
3. Make content accessible
The handbook has nearly 4,000 pages (as of 2020), and no one knows all of it. To utilize this mountain of text, GitLab recommends adding a search function. First, GitLab uses a cloud search service called Algolia. Second, by making the handbook public, they ensure it hits on Google searches (this might be hard to imitate).
---
I have briefly explained the GitLab Handbook above. At MNTSQ, the legal tech startup where I work, we are also trying to build a highly transparent and scalable organization by incorporating the parts of GitLab's best practices that we should adopt. At our company, internal documentation is managed in a Git repository, and the process is such that not only the engineering team but also the paralegal team uses GitHub to submit PRs for internal documents. The field our company works in is the legal sector, which is an industry that deals with a certain type of "document collection." I believe there is a high degree of affinity between this domain and the handbook-first philosophy.
MNTSQ, a legal tech company, is currently hiring. If you are interested in a startup that is trying to build this kind of scalable document culture, please feel free to contact us!