Content Websites

Overview

This area has traditionally been referred to as “the handbook”, but over time has grown in scope to include multiple sites, projects, repos, and types of content.

Therefore, we are using the term “content websites” here to avoid ambiguity and properly frame discussions around this scope of responsibility.

See our direction page for more.

If you need help, please see the editing handbook section, or escalation information if it’s urgent.

Team Structure

The maintainer of this page (as indicated in the sidebar) is considered the DRI for GitLab’s “content websites”. At present, the roles and responsibilities are as follows:

This page further documents the scope and responsibilities of the DRI and their engineering reports.

What are the content websites?

1. The public handbook.gitlab.com website:
   1. While often referred to as “the handbook”, this website also serves a wide variety of other content including the job families, and the teamops pages.
   2. handbook.gitlab.com is primarily backed by the gitlab-com/content-sites/handbook project and repo.
   3. Data (yml) files currently resides in the gitlab-com/www-gitlab-com repository.
2. The “Internal Handbook” at internal-handbook.gitlab.io:
   1. This website contains content that falls into the not public category. More details are available in the Internal Handbook usage page
   2. The Internal Handbook is backed by the gitlab-com/content-sites/internal-handbook project and repo.
3. The theme for the handbook sites is in the gitlab-com/content-sites/docsy-gitlab project.

What are NOT content websites?

1. The about.gitlab.com marketing website.
2. The gitlab.com site.
3. The docs.gitlab.com product documentation site.
4. Any other GitLab-managed or GitLab-owned website other than what is described above.

Issue triage

The following guidelines are used for triaging issues in content websites projects that are in-scope.

The triage guidelines use the product issue triage information as a basis. However, as the group structure and resources differ for the content websites, so do the guidelines.

Types of issues and resourcing

Handbook issues typically fall under one of the following:

1. Content: Anything related to updating the text in the handbook, including required fixes.
2. Feature: New or an enhancement of how the handbook works, such as theme, or shortcode.
3. Operations: Theme, pipeline, local development, linters, other maintenance, and related documentation.
4. Bug: Problem that prevents users from contributing, typically related to handbook operations.

The team overseeing the content websites generally only resources operations and bug issues, unless the issue is a blocker for contributing or using the handbook.

Priority

The priority label is used to indicate the importance of an issue and guide its scheduling. Priority labels are expected to be set based on the needs of GitLab. Priority can apply to any type of issue.

For bug issues, priority typically matches the severity. Match the priority to the severity if uncertain.

We encourage contributions for all issues, especially priority 3 and 4 issues, to be addressed sooner.

Severity

Severity labels help us determine urgency and clearly communicate the impact of a ~“Handbook::bug” on users.

Content issues, such as typos, are not bug issues. Severity may be applied, but

The severity should be determined based the various factors in the table below. When an issue falls under multiple categories, use your best judgment.

Once you’ve determined a severity for an issue add a note that explains in summary why you selected the severity you did. This will help future team members understand your rationale so they will know how to proceed with acting upon the issue.

Timeline for resolution is based on priority.

Triage bot

Please see the relevant project readme for implementation information.

View page source - Edit this page - please contribute.