Docs project maintenance tasks, August 2024

Technical Writing recurring tasks for: 2024-08

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:

Review the Kramdown build logs for warnings.
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 have tests that must be run locally on your workstation. 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 gitlab-org/gitlab-docs to check if any redirect files need to be removed. This automatically creates MRs in every project that has redirect files that have expired:
```
DRY_RUN=true bundle exec rake docs:clean_redirects
```
  If the task runs without errors, run the same command without DRY_RUN=true:
```
bundle exec rake docs: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:
  - In this MR, docs-lint links failed because the deleted file was referenced somewhere else. You need to edit the files where the deleted doc was referenced and update them with the new doc URL (its redirect_to value).
  - In this MR, the ui-docs-links-lint 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.
  - In this MR, the docs-lint markdown job failed because files with names that contained dashes were removed. You need to update the number of FILE_NUMBER_DASHES in the lint-doc.sh file. Changes to this file trigger a longer pipeline and require an additional review from Code Owners.
2. Add the gitlab-docs 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 gitlab-docs 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 gitlab-org/gitlab-docs:
```
make check-pages-not-in-nav
```
2. Open a few MRs to add pages to the nav. Assign the MR to the writer in the area. You don't need to add all pages to the nav, just add a few as you have time.
3. 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 scripts/pages_not_in_nav.js.
Search for <!--- start_remove and delete any content with dates in the past.

Remote tasks

The following tasks have tests that you can run from pipelines in the gitlab-docs 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 Run TW chores jobs scheduled pipeline.
Go to the pipelines page and find the pipeline you just triggered at the top. The pipeline has two stages.

The first stage runs the compile_dev job automatically:
- Review the Kramdown build logs for warnings. Check the compile_dev job log, and search for kramdown warning messages (which are usually caused by malformed Markdown).
  - Ignore warnings for files in the /blueprints and /solutions folders, and de-prioritize warnings for content in the /development folder (do other content first).
  - If the job log is truncated, select Complete Raw near the top to view the full log.
  - A warning might be reported for a specific line number, but this is often inaccurate. Check several lines above or below.
  - If the warning is reported for line 1 in a file, it's likely the problem is in a Markdown table, which could be anywhere in the file.
The second stage has three manual jobs. Select Run on the jobs you want to run:
- Check for unlinked images. Run the test_unlinked_images job, which checks all 4 projects to see if any images are no longer in use. It takes 40+ minutes to run, so you may want to start this job first, then work on the other tasks while waiting.
- 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/gitlab-docs/-/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 test_EOL_whitespace job to find all pages with lines that have trailing whitespaces and fix them.
  
  In each project's doc or docs directory, run:
```
markdownlint-cli2 --config .markdownlint/.markdownlint-cli2.yaml '**/*.md'
```
  Create a merge request with the 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

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:

Edited Aug 21, 2024 by Jon Glassman