Migrate support handbook content from `www-gitlab-com` to `handbook`
Problem Statement
What is the problem?
Company wide we're moving towards handbook
(handbook.gitlab.com) as the SSOT
for handbook content over www-gitlab-com
.
Why is this a problem?
We have a lot of content in www-gitlab-com
that will need to move over.
Proposal
In gitlab-com/content-sites/handbook!323 (merged)
we merged the first batch of content from www-gitlab-com
, so at merge date
all content is duplicated.
This issue is to plan out and execute the final migration.
During this process www-gitlab-com
is still the SSOT and all MRs to
content should be made there. The content in handbook.gitlab.com will be updated
when we make the final migration.
Timeline
- Review content in
handbook
for any content errors or things that didn't migrate over smoothly. Note them. - Evaluate what our strategy for redirects will be: some workflows are frequently used and deleting content from
www-gitlab-com
with a generic redirect will inhibit results. - Choose a date for migration, communicate using the standard change request process.
Migration
DRI: @jamiemaynard
-
Create an MR that updates content in handbook
fromwww-gitlab-com
gitlab-com/content-sites/handbook!382 (merged)- update this MR with any content fixes discovered in the review
-
Create an MR that removes all content in www-gitlab-com
and adds appropriate redirects gitlab-com/www-gitlab-com!127679 (merged) -
Ensure codeowners is ported over. gitlab-com/content-sites/handbook!435 (merged)
Desired Outcome
What does success look like?
- All content moved over
- Minimal disruption to support workflows
Process Change
The Story
Support portion of the handbook will be migrated to the new handbook on 2023-08-14 as part of the company migration effort.
The Roles
Role | Description |
---|---|
Champions | @jamiemaynard on migration effort, Support: @klang with comms support from @cynthia |
Users | All of Support |
Impacted Non-Users | All other departments and divisions that refer to support handbook pages |
Schedule
- Code freeze at 08:00 UTC
2023-08-11
- Rollout on
2023-08-14
Training
No training required.
Things to be aware of:
- Any open MRs will need to be "migrated" to the new handbook by opening a new MR in the new handbook. If there was discussion on the old one, please link to it.
- New handbook linter is stricter, such as using
*
for emphasis and strong instead of_
. - Who can merge is based on codeowners, not role. That is, you do not need to be a maintainer.
- Other notes from Jason in #5135 (closed).
Action Plan
DRI: @klang
and @cynthia
-
Create an item in the SWIR to announce the change and include The Story on date
- NOTE: On the SWIR form, add the
Manager Attention
tag for policy changes and action items for Support Managers specifically (you can add multiple tags to a SWIR item) - SWIR item: https://gitlab.com/gitlab-com/support/readiness/support-week-in-review/-/issues/853
- NOTE: On the SWIR form, add the
-
Post a message in the #support_team-chat
Slack channel (or other support channel as appropriate) announcing the change and pointing to the SWIR announcement ondate
-
Schedule Slack "refresher" messages to cover all regions
-
-
Announce the change and tell The Story in Team meetings by 2023-08-09
-
EMEA team meeting -
AMER team meeting -
APAC team meeting
-
-
Other communications channels -
EWIR -
Recruiting channel -
sales, customer-success channels
-
-
Update all relevant links in: -
support-training project support-training!1280 (merged) -
support-team-meta https://gitlab.com/gitlab-com/support/support-team-meta/-/merge_requests/132 -
ZD macros project https://gitlab.com/gitlab-com/support/support-ops/zendesk-global/macros/-/merge_requests/603 -
ZD triggers/automations/apps/portal/etc. - https://gitlab.com/gitlab-com/support/support-ops/support-ops-project/-/issues/965
-
-
Report back on change adoption, concerns, etc. by 2023-08-18
Manager Acknowledgement Section
Please make sure that your direct reports are aware of this change!
Expectations
Awareness of change, especially training/things to be aware of section.
Due Date
Check off your name by midnight UTC on: 2023-08-11
Names
Remove any subsections that are not applicable to your issue.
Support Managers
Sorted alphabetically by region / GitLab handle
AMER + USFed
APAC
EMEA
Ops
-
@jcolyer (remove backticks if Support Operations involvement is necessary for this)
Senior Management team
-
@lbot -
@lyle -
@shaunmccann -
@vparsons -
Senior Director or VP
Follow-Up Plan
Rollback will not be possible. Any adjustments/fixes required, please let @jamiemaynard
and/or @klang
know.