Handbook Roadmap

Documents development plans for the handbook

Introduction

This page will be for documenting and sharing plans for the handbook in true GitLab fashion: iteratively and transparently. Like the handbook overall, this roadmap will always be a work in progress—a living document.

Everyone is welcome to browse and contribute to our open handbook issues. If there’s something you’d like to report or something you’d like to see on this roadmap then please don’t hesitate to open a new issue. Contributions are welcome and appreciated!

Ongoing work

Small improvements such as link updates and text tweaks are constantly being made, but small changes can be made as quickly as updating the roadmap, so they don’t need to be mentioned here unless they are part of a larger effort.

Roadmap

What	When	Status
Handbook Migration	March 2023 to March 2024	Ongoing
Handbook AMA Livestream	October 2023	Planning
Handbook Issue Triage Livestream	October 2023	Planning
Handbook Client-side Features	December 2023
Handbook Search Improvements	TBC
New Team and Pets Site	TBC

Handbook Migration

After years of exponential growth and evolution and the significant accumulation of technical debt the decision was taken to migrate the Handbook from www-gitlab-com to its own repository and rearchitect how the handbook is generated. Where as previously the handbook was generated using Ruby and Kramdown the new handbook is generated using Hugo. This change has significantly decreased the time it takes to generate the site and get changes to the Handbook published.

Migrations are seldom easy. There is 12 years worth of commit history as well as almost 3000 pages worth of content with changes and updates being made every day. This has necessitated an iterative approach to migrating the handbook. We’ve broken the Handbook down in to sections, weighted those section by complexity of the migration and produced the following Timetable. During this time content will be split between https://about.gitlab.com and https://handbook.gitlab.com.

For more details see the Migration Timetable and Status section below.

Introduce Handbook AMA Livestream

The handbook is both a living document and an actively developed web site. GitLab features are also constantly being tried out on the Handbook. There is a plan to introduce a Ask Me Anything about the Handbook in keeping with our commitment to our values. This will be a once a month 25 minute livestream initially where people can ask anything relating to the handbook.

Introduce Handbook Issue Triage Livestream

To increase transparency of how Handbook issues and requests get treated its planned to introduce a new fortnightly livestream where the issues are gone through, commented on and prioritized. Any on going issues will also get updates talked about.

Client-side Features

The Handbook is a statically generated site by there are times when we need to put out notifications about pages or on-going work. The recently lead to the introduction of notifications to the handbook. This was done primarily to advise of the ongoing Handbook migration work. There are plans to build on this to notify of deprecated pages, to allow a watch list of pages and other client-side features.

Handbook Search Improvements

Currently there is no combined search between https://about.gitlab.com and https://handbook.gitlab.com and the internal handbook. Additionally the handbook search feature on https://handbook.gitlab.com is Client Side powered using a script called Luna. The vision is that searching the Handbook should be simple and accessible. Once the migration is completed the next significant bit of work will be to improve search across the handbooks.

New Team and Pets site

The current Team and Pets pages in company are quite complex and have not been included in the handbook migration as these pages aren’t really handbook content. So a decision has been taken to split these pages in to their own site once the migration has been completed. This may include other elements such as the compensation calculator and the organisation chart as well as using WorkDay as the Single Source of Truth for team data.

Migration Timetable and Status

Timetable

Status	Section	Total Pages	Markdown Pages	ERB Pages	Start	Finish
✅	Job Families	408	408	0	2023-03-28	2023-03-31
✅	TeamOps	7	0	7	2023-04-19	2023-04-21
✅	Company Handbook Content	52	49	3	2023-05-02	2023-05-12
✅	Tools and Tips	12	12	0	2023-05-16	2023-05-19
✅	Infrastructure Standards	21	21	0	2023-06-06	2023-06-09
✅	IT Self Service	12	12	0	2023-06-27	2023-06-30
✅	Support	212	208	4	2023-07-31	2023-08-14
✅	CEO and CoST	14	12	2	2023-08-15	2023-08-18
✅	Company	161	137	5	2023-08-30	2023-09-01
✅	Security	153	149	3	2023-09-05	2023-09-08
🚧	People Group	211	192	18	2023-09-18	2023-09-28
⚡	Culture	134	67	45	2023-10-02	2023-10-04
⚡	Finance	83	68	16	2023-10-04	2023-10-06
⚡	Product	414	351	64	2023-10-10	2023-10-13
📖	Marketing	415	385	28	2023-10-24	2023-10-26
📖	Sales	468	420	44	2023-11-07	2023-11-09
📖	Legal	67	67	0	2023-11-20	2023-11-23
📖	Engineering	810	257	553	2024-01-09	2024-02-19
📖	Team	3	0	1	TBC	TBC

Status Key

⚡ - This content will be migrated on the start date indicated
📖 - This content is in the planning stages of its migration and the start and finish dates are guides only
🚧 - This content is in the process of being migrated
✅ - This content has already been migrated to the new handbook

For more details see the Handbook Roadmap.

Migration calendar

We are providing a Google Calendar with all the dates for the migration in. This also includes public holidays and notable dates for the US and UK and other dates important to the migration team.

If the above iFrame is blank you can also access the Calendar Directly.

Why this order

The order is based largely on the table of contents for the handbook but its been weighted slightly so that those sections with lots of Ruby Template files (erb) are pushed to the bottom of the list. The idea is that content which is easier to move is the content which moves first. This will give more time for those teams who are using ruby templating to move their content to markdown. Where content can’t be easily moved to Markdown this will give the Handbook team time to work with teams to find and develop solutions to meet their needs.

We also hope to run in parallel the migration of the Engineering content from the existing handbook to the new handbook which we hope will reduce the time it takes to migrate all of the content from www-gitlab-com. If we are unable to do this we’ll still migrate engineering after Company Handbook Content.

Dates and order subject to change

This is the order we have identified to migrate content but it is subject to change based on factors such as operational need and how smooth the migration goes for each section. We won’t hesitate to bring forward a migration date if the current piece of content has moved smoothly and quickly. We’ll also communicate changes in #whats-happening-at-gitlab and #handbook on Slack.

Migration Status

What is moving next?

What are we moving: People-Group

Status Expected to complete: 2023-09-28

What content is moving

The following content has been earmarked as the next content to move. This will be done as a set of merge requests from 2023-09-18 . The content will then be checked, markdown errors fixed and merged in to the new handbook. The content on the about site will be removed and redirects setup 2023-09-28 .

Anti-Harassment
Entity
Hiring
Incentives
Labor and Employment
Leadership
Paid Time Off
People Group
Total Rewards
Travel

How will this be done

We hope to do this as a series of small MRs over the course of a week. Each of these sections is typically only a page or two. So we shall one small section at a time over the course of 4 days. Each move is a pair of MRs. One brings the content over to the new handbook while the other removes the content from www-gitlab-com and sets up a redirect to the new content.

If you have any questions about this please feel free to ask in #handbook on Slack or reach out directly to @jamiemaynard.

The break down of whats moving

Job Families

Completion Date: 2023-03-31

Content to move:

Job Families