Skip to content

Docs project maintenance tasks, May 2025

Technical Writing recurring tasks for: 2025-05

Each month, the Technical Writer assigned to recurring tasks ensures the following tasks are completed to help minimize technical debt.

Suggested order

These recurring tasks require a varying amount of time to complete. To make efficient use of your time, they are grouped according to the amount of time they usually take.

These tasks can sometimes take a long time:

  • Check for broken external links.
  • Search for and remove expired redirect files.
  • Search for and report on pages not in the global nav.

These tasks usually don't take as much time:

  • Look for uncompressed images.
  • Check for unlinked images.
  • Check for trailing whitespace.

Local tasks

The following tasks must be run locally on your workstation. Before performing these tasks, make sure you have an updated docs-gitlab-com repository:

make setup

Then update all local docs content:

make update-all-projects

Finally, ensure you're authenticated with glab:

$ glab auth status

gitlab.com
✓ Logged in to gitlab.com as <username> (<$HOME>/.config/glab-cli/config.yml)
✓ Git operations for gitlab.com configured to use ssh protocol.
✓ API calls for gitlab.com are made over https protocol.
✓ REST API Endpoint: https://gitlab.com/api/v4/
✓ GraphQL Endpoint: https://gitlab.com/api/graphql/
✓ Token: **************************

To perform these tasks:

  • Look for uncompressed images.

    Details

    1. Run the following command in gitlab-org/gitlab to check if any uncompressed images exist and compress them:

      bin/pngquant compress

      If you get an Error: pngquant executable was not detected in the system, try installing pngquant using Homebrew: brew install pngquant.

    2. If there are any results, create a new branch and then a merge request. Assign to any TW for merge.

  • Search for and remove expired redirect files.

    Details

    1. Run the following command in docs-gitlab-com to check if any redirect files need to be removed. This automatically creates MRs in every project that has redirect files that have expired, and opens an MR in docs-gitlab-com to add the expired redirects to redirects.yaml.

      make clean-redirects

      The task only removes the expired redirect files. There might be cases where some docs checks fail, so you'll need to fix those yourself. For example:

      • docs-lint links error: Job failed because the deleted file was referenced somewhere else.

        Check the pipeline error message to identify which files reference the deleted document. In each file that references the deleted document, update the URL to the new location (the redirect_to value).

      • ui-docs-links-lint error: Job failed because the deleted file was referenced in a help link in the UI.

        Open an MR to update the UI link. When merged, rebase your redirects MR to pick up the fix.

      • docs-lint markdown error: Job failed because the number of filenames or directory names with dashes changed.

        In the lint-doc.sh file, update the FILE_NUMBER_DASHES or DIR_NUMBER_DASHES values to match the new number of filenames or directory names with dashes. Changes to this file trigger a longer pipeline and require an additional review from Code Owners.

    2. Add the docs-gitlab-com MR as a dependency to any MRs that delete the redirect files in the other projects. Assign all MRs to the same Technical Writer, and explain that the docs-gitlab-com MR should be merged first, followed by the MRs in the other projects.

      Be sure to @-mention hsmith-watson in Marketing so they can update any now-expired links on about.gitlab.com.

  • Search for and report on pages not in the global nav.

    Details

    1. Run the following command in a local checkout of gitlab-org/technical-writing/docs-gitlab-com:

      make check-pages-not-in-nav

    2. For each missing page, check with the group's assigned writer to confirm if it should be added to or excluded from the global nav.

    3. Open an MR per page to add it to the global nav. Assign the MR to the writer assigned to the group. You don't need to add all pages to the global nav, just add a few as you have time.

    4. If you find false positives and:

      • The false positives are individual pages, add ignore_in_report: true to the page's metadata.
      • All the files in a directory are false positives, add the directory to the excludePatterns array in scripts/pages_not_in_nav.cjs.

  • Search for <!--- start_remove and delete any content with dates in the past.

    1. Run the following command in a local checkout of gitlab-org/technical-writing/docs-gitlab-com:

      make find-expired-content

    2. Remove any expired content flagged by the script, create MRs as needed, and assign to any TW to merge.

  • Remove unlinked images.

    1. Run the following command in a local checkout of gitlab-org/technical-writing/docs-gitlab-com:

      make find-unused-images

    2. The script returns a list of image files if any are found. You can safely delete these images to save space in the repositories. Create MRs as needed and assign them to any TW to merge.

Remote tasks

The following tasks can run from pipelines in the docs-gitlab-com project. Some of the tests may not return any results, and no further work is required for that task. To perform these tasks:

  1. Go to the pipeline schedules page.

  2. Select Run for the Monthly tasks (manual) scheduled pipeline.

  3. Go to the pipelines page and find at the top the latest pipeline called Monthly tasks pipeline.

    • Check for broken external links. Run the test_external_links_charts, test_external_links_gitlab, test_external_links_gitlab_runner, test_external_links_omnibus_gitlab, and test_external_links_operator jobs. The jobs can produce a lot of output, so scan through the lists and prioritize the fixes as follows:

      Details
      • Links returning a 404 error. These links are likely broken for customers, so they should be fixed first. If you can't find a replacement link, lean toward removing the link and surrounding content.
      • Redirects. At some stage, the redirects might be removed too, so it's better to update them now. Fix as many as time allows. When evaluating redirects:
        • Check the forwarded link, as it may also be broken or may redirect again to another page.
        • Check if the URL has a forward slash (/) at the end when you visit it, and ensure your fix does the same. Many redirect warnings are caused solely due to the presence or absence of the slash.
        • Check for section title links (anchors), such as #section-title. You may need to add the #section-title manually.
        • Create an issue and assign it to an SME if the updated link does not provide the desired information.
      • False positives. This is where a failing link is actually valid, for example, where a website needs authentication, or the site server returns a response the link checker sees as a failure. To fix this, exclude it from the link checker. Go to https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/blob/main/lychee.toml and add the link in the exclude = [] list, following the pattern of the other links already there. Fix as many as time allows.

    • Check for trailing whitespace. Run the lint:markdown-eol-whitespace job to find all pages with lines that have trailing whitespaces and fix them. To fix the trailing whitespaces, either:

      • In docs-gitlab-com, run:

        LINT_OPTIONS="--fix" make lint-markdown-eol-whitespace

      • In each project's doc or docs directory, run:

        markdownlint-cli2 --config .markdownlint/.markdownlint-cli2.yaml '**/*.md'

      Create a merge request for each project that required fixes and have them merged back to the project's default branch.

If you have problems (such as broken links without obvious replacements), ask in the appropriate Slack channel, or open an issue/MR. Note that these tasks aren't intended to solve 100% of related technical debt.

Final steps

Edited by Marcel Amirault