Support handbook migration
What's the deal
As you may have noticed, a lot of team handbooks are being migrated to https://handbook.gitlab.com/handbook/ . Having done the support readiness migration myself, I would suggest Support migrate their handbook as a big team project!
Having just done the migration for Support Readiness, I learned a good bit of things during the process I wanted to share to help make the process easier!
If Support feels it is best they do their handbook's migration, feel free to make an issue to plan it all out! I just wanted to share all that I learned in the process of doing Readiness's migration to help out! And please feel free to use myself as a resource!
Things I learned
Viewing changes locally
As there was a new file structure going on, I wanted to see how what I was doing looked. After speaking with Jamie, we found the best way to do this was via Docker, doing something like this:
cd /path/to/repo
docker run --rm -it -v $(pwd):/src -p 1313:1313 klakegg/hugo:0.107.0-ext-ubuntu-onbuild server
This compiles all the stuff and makes the handbook viewable locally via http://localhost:1313/
Linting
The new handbook requires we follow proper linting protocols. This was a big "gotcha" to me, as many of what I did flagged (let's say about 80% of the files).
Some common ones I hit (a lot) were:
- Use
-
for lists, not*
- Code blocks (i.e. things using ```) should specify the type of code it is. In cases where it is not any form of code, use ```string
- Inline code blocks (i.e things using `code`) should not start or end with spaces.
I'm sure there are others we may encounter, so it is best to test your code before commit'ing it. After speaking with Jamie, we found the best way to run the gambit on your code to ensure it passes linting pipelines was via Docker, doing something like this:
cd /path/to/repo
docker run -v $(pwd):/workdir davidanson/markdownlint-cli2:next -f content/\*\*/\*.md
The table of contents auto-generated
The table of contents will autogenerate for items using headers 1-4 (#
, ##
, ###
, ####
), but it will not add to the table of contents for anything past that.
The navigation sidebar auto-generates
The left-side navigation bar is auto-generated based off the file structure and the values in the metadata. So it is important to get that right! Knowing this, you might want to re-arrange how your handbook is currently setup to make it easier to navigate via this sidebar when you do your migration (readiness opted to)
Every file should have metadata
Every file should have metadata as the starting point! This helps with the navigation sidebar and the like. You would want to ensure they all include something like:
---
title: The name of the page
description: A description of the pathTechnical Support team
canonical_path: "/path/to/file/in/repo/"
---
As an example, to make the metadata for https://about.gitlab.com/handbook/support/workflows/working_with_support_ops.html, you might do something like this (assuming the no pathing changes):
---
title: Working with Support Operations
description: Workflow for working with Support Operations
canonical_path: '/handbook/support/workflows/working_with_support_ops/'
---
Index files
To make an index file for a folder, you would name it _index.md
. The index file will also contains links to all the immediate files within that folder itself. As an example, the index file for the Support Readiness, Operations team has code that looks like this:
---
title: Readiness Team
description: Everything you wanted to know about the Readiness sub-department
canonical_path: "/handbook/support/readiness/"
---
## Purpose
The purpose of Support Readiness is to:
- foster and support an environment where individuals and the larger support team are continuously improving.
- ensure the team has ready access to information about activities that will affect the customer experience.
- create operational efficiency and reduce error rates by building tooling that mechanizes or automates engineer workflows.
- evaluate and measure our customer service quality and develop plans to execute globally consistend service delivery.
## Support Readiness Links
- [Readiness Subgroup](https://gitlab.com/gitlab-com/support/readiness)
- [Operations Team](./operations)
But the end result looks like this: https://handbook.gitlab.com/handbook/support/readiness/
Notice all the links at the bottom. We didn't have to code that, the renderer did it for us automagically!
All files should be written via markdown and use that extension
All the files are pure markdown and should end with .md
The search is amazing
This may not be related to the actual migration, but I was blown away by the search mechanism. With the Operations stuff in place, I can know search for tags
, missing_sla
, or missing sla
and the Operations tag page comes up in the search. Love that is is including the contents!
What if we want our git history though?
Jamie and the team have made some awesome scripts on the new project (in the aptly named scripts
folder) to help with this! The important bits are where it does a pair of git filter-branch
operations on a copy of the www-gitlab-com
repo before pulling the content using a git pull
in to the new handbook repo from the copy. This preserves the git histories on the files which are being migrated
Readiness opted out of doing all this, but it is totally an option! We decided we wanted a complete re-vamp of our structure, so it didn't quite make sense for us.
But what about after we merge the code?
After Readiness got our stuff in the new handbook, I did the following:
- Made all links to
about.gitlab.com/handbook/support/support-ops/
redirect tohttps://handbook.gitlab.com/handbook/support/readiness
using this code in data/redirects.yml (in the old handbook's project)- sources: - /handbook/support/support-ops/ target: https://handbook.gitlab.com/handbook/support/readiness/operations comp_op: ^~
- Found any old references to the links and updated them (in files not being moved)
- Deleted all the old pages