Sharing and retrieving information is a crucial part of everyday work life. Where do you get information from, be it about hiring processes, social media guidelines, or reporting expenses? At GitLab, all of that can be found in the handbook – have a look, it's public! Sid, our CEO, wrote about the importance and the open sourcing of our handbook about two and a half years ago. Back then we were just shy of 100 employees. In this post we will look at how the handbook has developed over time, how we interact with it, and how it still works for over 550 employees.
One book to guide them all
At the time of writing, the handbook contains about 605,000 words. While probably a bit less captivating than the tales of Frodo and Middle Earth, we have composed more pages than "The Lord of the Rings" and "The Hobbit" combined, since the first commit in 2015. It would take around 50 hours of continuous reading to cover the whole handbook, front to back.
Is it overwhelming to read through it all?
It would be, but as the handbook covers a wide range of topics, you probably don't need to read every single word. As the handbook changes over time it is not necessary to memorize it all, but it is more important to remember how to retrieve information. So as long as you know where to find something, you are on the safe side.
It would take around 50 hours of continuous reading to cover the whole handbook, front to back
One book to be written by them all
Graph showing the growth of the handbook, broken down by subcategory, over time (May 2015 – April 2019)
Currently all knowledge in the handbook is spread across 550 unique web pages, with the average page containing around 1,100 words. The most words have been written in the subcategory engineering (138,000 words), with marketing a close second (115,000 words). Typically, as teams grow, more of their processes get documented in the handbook, which leads to a natural growth of the respective category.
The most words have been written in the subcategory engineering (138,000 words)
Who contributes to the handbook?
You might think that there is someone special who writes all those pages, but it's important to remember that everyone can contribute to the handbook. It is actually part of our onboarding process to improve something about the handbook – whether that's clarifying wording or making it easier to find something. Nothing is exempt from change; even our core values are adjusted over the course of time.
How do you make changes to the handbook?
If someone at GitLab or from the wider community wants to change something, they follow a simple workflow that is familiar to every GitLab user:
- Create a merge request which introduces the change.
- Discuss the merge request with the stakeholders.
- Iterate on the change and come to an agreement.
- Let the merge request be merged.
More important changes (not every typo of course!) are then announced via Slack or our company call. The handbook also has its own changelog which you can check regularly to see what has been changed over time.
One book to be read by them all
In 2018 we had several hundred thousand page views on pages in the handbook. It is hard to tell which views come from GitLab team-members and which from the wider community. Among the most-read pages are our Markdown Guide, the pages about global compensation, our values, the hiring process, our product, benefits, and how to communicate. These pages are topics of general interest to people within and outside the company. What could be a better resource to potential candidates than those pages that show the inner workings of GitLab?
How do you find anything in the handbook?
The handbook has a search function; you can use the index page as an entry point, or just use your favorite search engine to find information. Whenever someone asks a question in our Slack, there is a high probability that someone will answer with a link to the handbook. If someone asks a question that has no answer in the handbook, we highly encourage people to add that information to document it and make it easier for future GitLab team-members to find answers.
Whenever someone asks a question in our Slack, there is a high probability that someone will answer with a link to the handbook
One book to be the future
We hope that this glimpse into the handbook is as interesting for you as it was for us. In an all-remote company it is especially important to write everything down, so that no matter where you are in the world or what time zone you choose to work in, the information you need is accessible. At the moment we are happy to say that we think that the handbook works as well for us now as it did with 100 employees. It aligns with our values more than ever.
For us it is the most transparent way to collaborate on documentation of company internals. We are able to efficiently iterate on topics, resulting in more in-depth coverage over time. Personally the authors cannot see many reasons why the handbook should not be able to scale even further. Eventually it will evolve further, from the three tomes we have today, to a digital encyclopedia. We are definitely excited to see what the future holds!
Have you taken inspiration from our handbook? Let us know by tweeting @gitlab.
Photo by Beatriz Pérez Moya on Unsplash
