Technical Writing recurring tasks for: 2025-11

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.
Search for and lint trailing whitespaces in files.

These tasks usually don't take as much time:

Look for uncompressed images.
Check for unlinked images.

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 redirects error: Job failed because there's a missing redirect for a deleted or moved page.
    
    Although this is automatically resolved when the docs-gitlab-com MR is merged, do check if there's a legitimate failure. For example, you might be removing a redirect that's already referenced in the global nav. In that case, update the global nav and remove the entry.
  - 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 or rubocop-docs 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.
  
  Make sure that every MR has both the Delete source branch when merge request is accepted and Squash commits when merge request is accepted options selected.
  
  Be sure to @-mention hsmith-watson in Marketing so they can update any now-expired links on about.gitlab.com.
3. After everything is merged, check the status of the test:check_global_nav_entries job in the next hourly pipeline in docs-gitlab-com. In some edge cases, the job might start failing because of the removal of a redirect file that the navigation points to. If it failed, create an MR to either update the navigation entry to point to the correct file, or remove the entry if the file is completely removed.
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.
Search for and lint trailing whitespaces in files.
Details
1. Run the following command in docs-gitlab-com to check if docs files have any trailing whitespaces and fix them. This automatically creates MRs in every project that has trailing whitespaces.
```
make lint-markdown-eol-spaces
```
  The task only removes the trailing whitespaces. No pipeline errors are expected.

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:

Go to the pipeline schedules page.
Select Run for the Monthly tasks (manual) scheduled pipeline.
Go to the pipelines page and find at the top the latest pipeline called Monthly tasks pipeline.
- Check for broken external links. The external link test 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.

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

Improve this template, if needed.
Create a new issue for the next month's chores, and assign it to the next TW on the schedule.

Link the new issue here: