# Technical Writing recurring tasks for: 2026-02 Each month, the Technical Writer [assigned to recurring tasks](https://handbook.gitlab.com/handbook/product/ux/technical-writing/#regularly-scheduled-tasks) ensures the following tasks are completed to help minimize technical debt. > [!important] > Make sure that every MR created for this work: > > - Has an assignee (yourself) > - A milestone > - A link to _this_ issue. ## 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. ### Initial setup Before performing these tasks, make sure to do all the following steps: 1. Update your `docs-gitlab-com` repository: ```shell make setup ``` 1. Then update all local docs content: ```shell make update-all-projects ``` 1. Update the `sitemap.xml` by running `hugo`: ```shell hugo ``` 1. Finally, ensure you're [authenticated](https://gitlab.com/gitlab-org/cli/-/blob/main/README.md#oauth-gitlabcom) with `glab`: ```shell $ 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: ************************** ``` ### Tasks - [x] **Look for [uncompressed images](https://docs.gitlab.com/development/documentation/styleguide/#compress-images).** <details><summary>Details</summary> 1. Run the following command in `gitlab-org/gitlab` to check if any uncompressed images exist and compress them: ```shell bin/pngquant compress ``` If you get an `Error: pngquant executable was not detected in the system`, try installing `pngquant` using Homebrew: `brew install pngquant`. 1. If there are any results, create a new branch and then a merge request. Assign to any TW for merge. </details> - [x] **Search for and remove expired redirect files.** <details><summary>Details</summary> 1. Run the following command in `docs-gitlab-com` to check if any redirect files need to be removed. This [automatically creates](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/blob/main/doc/tasks.md#expired-redirects) 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`. `ISSUE_NUMBER=` should point to _this_ issue's number. ```shell make clean-redirects ISSUE_NUMBER=1590 ``` 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](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/lint-doc.sh), 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. 1. 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`. 1. 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. </details> - [x] **Search for and report on pages not in the global nav.** <details><summary>Details</summary> 1. Run the following command in a local checkout of `gitlab-org/technical-writing/docs-gitlab-com`: ```shell make check-pages-not-in-nav ``` 1. 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. 1. 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. 1. 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`](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/blob/main/scripts/pages_not_in_nav.cjs?ref_type=heads#L15). </details> - [x] **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`: ```shell make find-expired-content ``` 1. Remove any expired content flagged by the script, create MRs as needed, and assign to any TW to merge. - [x] **Remove unlinked images.** 1. Run the following command in a local checkout of `gitlab-org/technical-writing/docs-gitlab-com`: ```shell make find-unused-images ``` 1. 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. - [x] **Search for and lint trailing whitespaces in files.** <details><summary>Details</summary> 1. Run the following command in `docs-gitlab-com` to check if docs files have any trailing whitespaces and fix them. This [automatically creates](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/blob/main/doc/tasks.md#markdown-eol-spaces) MRs in every project that has trailing whitespaces. `ISSUE_NUMBER=` should point to _this_ issue's number. ```shell make lint-markdown-eol-spaces ISSUE_NUMBER=1590 ``` The task only removes the trailing whitespaces. No pipeline errors are expected. </details> ## 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](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/pipeline_schedules). 1. Select **Run** for the **Monthly tasks (manual)** scheduled pipeline. 1. Go to the [pipelines page](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/pipelines) and find at the top the latest pipeline called **Monthly tasks pipeline**. - [x] **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><summary>Details</summary> - 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. </details> 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 - [x] **Improve [this template](https://gitlab.com/gitlab-org/technical-writing/team-tasks/-/blob/main/.gitlab/issue_templates/tw-monthly-tasks.md), if needed.** - [X] Create a new issue for the next month's chores, and assign it to the next TW [on the schedule](https://handbook.gitlab.com/handbook/product/ux/technical-writing/#regularly-scheduled-tasks). - [X] Find and replace `<issue_number>` with the new issue's number. It is used in the **lint trailing whitespaces** and **clean redirects** tasks. - [X] Link the new issue here: https://gitlab.com/gitlab-org/technical-writing/team-tasks/-/work_items/1614