Sometimes you want to have real time editing of a proposal during a meeting and you need to use a Google Doc for that. When doing so the first item should be the URL of the handbook page this content will be moved to when the meeting is over.
Documenting in the handbook before taking an action may require more time initially because you have to think about where to make the change, integrate it with the existing content, and then possibly add to or refactor the handbook to have a proper foundation. But, it saves time in the long run, and this communication is essential to our ability to continue scaling and adapting our organization.
This process is not unlike writing tests for your software. Only communicate a (proposed) change via a change to the handbook; don't use a presentation, email, chat message, or another medium to communicate the components of the change. These other forms of communication might be more convenient for the presenter, but they make it harder for the audience to understand the context and the implications for other potentially affected processes.
Having a "handbook first" mentality ensures there is no duplication; the handbook is always up to date, and others are better able to contribute.
When asked during an INSEAD case study interview (shown above) about challenges related to being all-remote, GitLab co-founder and CEO Sid Sijbrandij provided the following reply.
The biggest problem is GitLab not working handbook first. We have an amazing handbook that allows us to collaborate, onboard new people, and think collectively.
However, it is counterintuitive to communicate changes to the handbook. The default of people, when they wish to communicate a change, is to send a Slack message, send an email, give a presentation, or tell people in a meeting — anything but make a change in the handbook.
It's slower for them. It's quicker to use any other form. If they make a change in the handbook, they first have to find the relevant part of the handbook, they sometimes have to adjust the handbook to make sure their change will fit in, they have to go through a technical process and a review or two, and they have to wait a bit before it's deployed.
It's slower than any other option. However, it allows people that commit a change after that to build upon a change. When they take that extra time, it's building a foundation for the next thing.
I think of it as brick laying. Every piece of information is a brick. At GitLab, there is a well-structured house, and everyone adds to that one house. Because we're pretty particular on how we build it, it has a strong foundation and we can build it very high.
In every other company, they send the brick into the hands of people. Everyone is receiving bricks daily that they have to add to the house they're building internally. They forget things and things are unclear. A lot of context has to be created because there is no context around where to place the bricks.
So, you can end up with a thousand houses that look quite different, that are all hanging a bit, and each time you add a brick to the top one pops out at the bottom. — GitLab co-founder and CEO Sid Sijbrandij
Please follow these guidelines and remind others of them.
#handbookchannel to stay up-to-date with changes to the handbook
When working to get your change merged quickly, make sure you are asking the appropriate team members with merge rights. Not sure who is responsible? Consult (and add to) the
#whats-happening-at-gitlabslack channel if applicable. You can remind other people of this by asking "Can you please send a merge request for the handbook?"
Think about the information architecture to eliminate repetition and have a Single Source of Truth (SSoT). Instead of repeating content cross-link it (each text has a hyperlink to the other piece). If you copy content please remove it at the origin place and replace it with a link to the new content. Duplicate content leads to having to update it in multiple changes, which is a lot of work and very easy to forget. If you forget one of the pieces of content is out of date. Make sure to always cross-link items if there are related items (elsewhere in the handbook, in docs, or in issues).
The handbook is organized by function and result to ensure every item in it has a location and owner to keep it up to date.
If a page includes more than two headings (especially if it's larger than a single "screen"), add an automatically generated Table of Contents (ToC) by copying line 6 to 10 in this MR). Headings should have normal capitalization: don't use ALL CAPS or TitleCase). After a heading, leave one blank line; this is not required in the standard, but it is our convention.
In an all-remote, asyncronous organization, each team member should practice handbook first. For more information on what it means to be handbook first, please refer to the why handbook first section of this page.
Skills and behaviors of handbook first as a Team Member:
Skills and behaviors of handbook first as a People Leader:
For E-Group, information may need to be iterated on or MR branches may need to be created before it is made public. Outside of E-Group, temporary access may be granted on a project-specific basis.
Compare Branch and Continue.
Submit Merge Request.
If you require project-based access, you can request temporary developer access in the
#private_repo_auth_request Slack channel. The CLO is DRI on approvals. Membership will be audited on a monthly basis by the Sr. EBA to the CLO to ensure accuracy.
How to keep your Git-Fork up to date is an easy tutorial to follow from the command line to keep the private handbook up-to-date, until mirroring is working.
The handbook is a living document and we'll occasionally need to change URLs or move pages. This is the process Growth Marketing uses to set up and manage redirects for about.gitlab.com.
It is each department and team member's responsibility to ensure the handbook stays current. People Operations Specialists will partner with a representative from each department (engineering, marketing, etc) through weekly reviews to verify the content in the handbook is accurate and follows the same format as outlined in the Guidelines. For questions on who to submit a merge request to, or assistance with the handbook, please reach out on the
#handbook Slack channel.
If you need permissions to directly merge changes to the handbook, please submit a New Access Request issue and follow the process for access approval. Request a 'Maintainer' role under www-gitlab-com. See here for a full description of roles and permissions.
Any changes to the handbook as part of this review will be shared in the
#handbook channel in Slack. People Operations Specialists will also ensure that questions asked in
#questions are documented and all announcements on the company call have a relevant link.
The Engineering team and all sub-teams track Handbook Update Frequency as a KPI, with varying targets per team. Currently, Engineering is the only Division tracking Handbook update frequency, so as to analyse and observe the effectiveness of this KPI.
Presentations are great for ephemeral content like group conversations and board presentations. Evergreen content like a leadership training should be based on the handbook. This is an important element of working handbook-first.
In the creation of presentations for evergreen content, please screenshot the handbook and provide links to displayed pages rather than copy and pasting content (or formatting a slide specifically to mirror handbook information). This approach shows a bias towards asynchronous communication, and rationale for this is below.
The presentation will look less polished, but the advantages outweigh that concern.
If a synchronous presentation is required, default to sharing your screen and viewing live handbook pages over a slide presentation.
Another company asked how we managed to work with the handbook because at their company it wasn't working: "There are many occasions where something is documented in the knowledge base, but people don't know about it because they never bothered to read or search. Some people have a strong aversion against what they perceive as a 'wall of text'."
We attempt to cover this in GitLab's guide to embracing a handbook-first approach to documentation.
To ensure that people's time is well spent looking at the handbook we should follow the 'handbook guidelines' above, and also:
Company handbooks frequently start as wikis. This format is more comfortable for people to work in than a static website with GitLab Merge Requests and GitLab Pages. However wikis tend to go stale over time, where they are badly organized and get out of date.
In wikis it is impossible to make proposals that touch multiple parts of a page and/or multiple pages. Therefore it is hard to reorganize the handbook. Because GitLab Merge Requests and GitLab Pages are based on distributed version control you can split the role of submitter and approver. This allows for a division of work that keeps the handbook up to date:
Wikis also do not encourage collaboration on changes, because there is no way to discuss a proposed change like there is with merge requests.
Remember that, like virtually everything we do, our handbook is open source, and we expect that other companies may use it as inspiration for their own documentation and practices. That said, the handbook should always be specific on what we do, not who we want to be, and every company will need to fill out their own handbooks over time. Our handbook falls under the Attribution-ShareAlike 4.0 International license.
If your company has been inspired by GitLab's handbook, we would love to know what inspired you. Please see our Inspired by GitLab page.
Every GitLab Handbook page has a search field near the top of the page for searching. See the Searching GitLab like a pro page for tips on searching the handbook faster and more efficiently.
If you run into trouble editing the GitLab Handbook there are various means of help available.
Team members, referred to as MR Buddies, are available to help you create a merge request or debug any problems you might run into while updating the GitLab Handbook.
For more serious problems, especially ones that are time sensitive or prohibiting access to important information, there is an escalation process to reach out to team members who are on-call to help resolve the problem.
GitLab team members with
merge rights, are team members who have the GitLab permissions to merge merge requests (AKA: maintainer-level permissions).
It is important that GitLab team members with maintainer permission use this responsibility responsibly.
Below are a few guidelines for GitLab maintainers: