The handbook started when GitLab was a company of just ten people to make sharing information efficient and easy. We knew that future GitLabbers wouldn't be able to see emails about process changes that were being sent before they joined and that most of the people who would eventually join GitLab likely hadn't even heard of us yet. The handbook was our way of ensuring that all of our company information was accessible to everyone regardless of when they became part of the team.
At GitLab our handbook is extensive and keeping it relevant is an important part of everyone's job. It is a vital part of who we are and how we communicate. We established these processes because we saw these benefits:
.1Reading is much faster than listening.
.2Reading is async, you don't have to interrupt someone or wait for them to become available.
.3Recruiting is easier if people can see what we stand for and how we operate.
.4Retention is better if people know what they are getting into before they join.
.5On-boarding is easier if you can find all relevant information spelled out.
.6Teamwork is easier if you can read how other parts of the company work.
.7Discussing changes is easier if you can read what the current process is.
.8Communicating change is easier if you can just point to the diff.
.9Everyone can contribute to it by proposing a change via a merge request.
.1A (process) problem comes up, frequently in an issue or chat.
.2A proposal is made in a merge request to the handbook.
.3Once merged, the change is announced by linking to the diff in the MR or commit. Major ones are put in the agenda of the company call. Medium ones are posted in on the #handbook channel for visibility, with a one line summary of the change . If there was an issue, close it out with a link to the diff.
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 mentality ensures there is no duplication; the handbook is always up to date, and others are better able to contribute.
Please follow these guidelines and remind others of them.
- Most guidelines in this handbook are meant to help, and unless otherwise stated, are meant to help more than being absolute rules. Don't be afraid to do something because you don't know the entire handbook, nobody does. Be gentle when reminding people about these guidelines. For example say, "It is not a problem, but next time please consider the following guideline from the handbook."
- If you ask a question and someone answers with a link to the handbook, they do this because they want to help by providing more information. They may also be proud that we have the answer documented. It doesn't mean that you should have read the entire handbook, nobody knows the entire handbook.
- If you need to ask a team member for help, please realize that there is a good chance the majority of the community also doesn't know the answer. Be sure to the answer to radiate this information to the whole community. After the question is answered, discuss where it should be documented and who will do it. You can remind other people of this request by asking "Who will document this?"
- When you discuss something in chat always try to to a URL where relevant. For example, the documentation you have a question about or the page that answered your question. You can remind other people of this by asking "Can you please link?"
- Remember, the handbook is not what we hope to do, what we should formally do, or what we did months ago. Make sure you change the handbook in order to truly change a process. To propose a change to a process, make a merge request to change the handbook. Don't use another channel to propose a handbook change (email, Google Doc, etc.).
- The handbook is the process. Any sections with names like 'process', 'policies', 'best practices', or 'standard operating procedures' are an indication of a deeper problem. This may indicate a duplication between a prose description of a process and a numbered list description of the same process that should be combined in one description of the process.
- When communicating something always include a link to the relevant (and up-to-date) part of the instead of including the text in the email/chat/etc. You can remind other people of this by asking "Can you please link to the relevant part of the handbook?"
- Everyone should subscribe to the #handbook channel to stay up-to-date with changes to the handbook
- To change a guideline or process, in the form of a merge request. After it is merged you can talk about it during the company call if applicable. You can remind other people of this by asking "Can you please send a merge request for the handbook?"
- When substantially changing handbook layout, please leave a link to the specific page of the review app . Along with the link, include as much info as possible in the MR description. This will allow everyone to understand what is the purpose of the MR without looking at diffs.
- Communicate process changes by linking to the (a commit that shows the changes before and after). If you are communicating a change for the purpose of discussion and feedback, it is ok to link to an . Do not change the process first, and then view the documentation as a lower priority task. Planning to do the documentation later inevitably leads to duplicate work communicating the change and it leads to outdated documentation. You can remind other people of this by asking "Can you please update the handbook first?"
- Like everything else, our processes are always in flux. Everything is always in draft, and the initial version should be in the handbook, too. If you are proposing a change to the handbook, whenever possible, . (Proposing a change via a merge request is preferred over an issue description). Mention the people that affected by the change in the merge request. In many cases, merge requests are easier to collaborate on since you can see the proposed changes.
- to a group of users, add it to the handbook and note as such. Then remove the note once the test is over and every case should use the new process.
- If someone inside or outside GitLab makes a good suggestion invite them to add it to the handbook. Send the person the url of the relevant page and section and offer to do it for them if they can't. Having them make and send the suggestion will make the change and will reflect their knowledge.
- When you submit a merge request, make sure that it gets merged quickly. Making single, small changes quickly will ensure your branch doesn't fall far behind master, creating merge conflicts. Aim to make and merge your update on the same day. Mention people in the merge request or reach them via Slack. If you get a suggestion for a large improvement on top of the exiting one consider doing that separately. Create an issue, get the exiting MR merged, then create a new merge request.
- If you have to move content have a merge request that moves it and does nothing else. If you want to clean it up, summarize it, or expand on it do that haver the moving MR is merged. This is much easier to review.
- Try to , what is the business goal, what is the inspiration for this section. Adding the why makes processes easier to change in the future since you can evaluate if the why changed.
- If you copy content please remove it at the origin place and replace it with a link to the new content. Think about the information architecture to eliminate repetition. Duplicate content leads to updating it in the wrong place, keep it DRY
- Make sure to always cross-link items if there are related items (elsewhere in the handbook, in docs, or in issues).
- The handbook is to ensure every item in it has a location and owner to keep it up to date. It's essential that we adhere to this hierarchy and that we not maintain separate structures for company training materials (e.g. onboarding materials, how-tos, etc.), videos, or other documentation.
- At times, a change of perspecitve may be desired. In those cases, link to relevant sections of the handbook liberally. See the onboarding template as an example.
- Avoid unstructured content based on formats like FAQs, lists of links, resource pages, glossaries, courses, videos, tests, or how-to's. These are very hard to keep up-to-date and are not compatible with organization per function and result.
- Instead, put the answer, link, definition, course, video, or test in the most relevant place. Use descriptive headers so that people can easily search for content.
- That said, please mix formats where and when appropriate in the handbook, even within a single page. Utilizing multiple formats can be valuable, and different people may prefer certain formats over others.
- Worry only about the organization , not about how the page will look if you embed varying types and formats of content.
- . If a page includes more than two headers (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 ).
- Headers should have normal capitalization: don't use ALL CAPS or TitleCase ).
- After a header, leave one blank line; this is not required in the standard , but it is our convention.
- Strongly consider learning how to edit the handbook using git and/or via the web IDE , and please read through the Writing Style Guidelines before contributing.
- Keep your handbook pages short and succinct. Eliminate fluff and get right to the point with the shortest possible wording. Keep in mind that the biggest challenge cited by new employees is the vast amount of information to take in during on-boarding.
- We don't need .gitkeep files in our handbook, they make it harder to quickly open a file in editors. Don't add them, and delete them when you see them.
- Anything more than a spelling correction is better done in the terminal than with the online editor. All people that are reluctant to update the handbook are not using the terminal, a local editor, and a local preview. Please follow the instructions in edit this website locally .
- When mentioning currency amounts that team members may need to convert to their local currency (e.g. benefits, expenses, or bonuses), link those amounts to our Exchange Rates section (e.g. 500 USD ).
Because the handbook is a living, breathing document, page names, locations, and URLs are bound to change over time. If you make a change that could break one or more links elsewhere in the handbook, it will be necessary for you to set up a redirect. Working with our NGINX setup is a technical process, so we rely on the Production team to help with these requests.
Please do not create meta refresh (client side or JavaScript) redirects. 301 redirects are the correct method for ensuring good SEO and user experience of our site.
- Old URL that needs to be redirected
- New URL where users should now be sent If you have any specific questions or concerns regarding the merge request, you can reach out via the
#production channel on Slack.
It is each department and team member's responsibility to ensure the handbook stays current. People Operations 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 ping the handbook content manager on GitLab or reach out on the '#handbook' Slack channel.
Any changes to the handbook as part of this review will be shared in the #handbook channel in Slack. People Ops will also ensure that questions asked in #questions are documented and all announcements on the company call have a relevant link.
.1It saves you the effort of creating a presentation.
.2People can easily find the handbook section later on.
.3The handbook is checked and improved as part of the preperation.
.4The content is open to contributions.
.5The content is integrated with the rest of our processes.
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'."
To ensure that people's time is well spend looking at the handbook we should follow the 'handbook guidelines' above, and also:
.2Have a great search function (we use Algolia), plus make it public so you can Google search
.3Test people on their knowledge during onboarding
.4Give real examples
.5Avoid corporate speak, describe things like you're talking to a friend
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 , not , and every company will need to fill out their own handbooks over time.