Docs maintenance: June 2021 [Marcin]
Technical Writing recurring tasks for: 2021-06
Previous issue: #438 (closed)
Each month, the Technical Writer assigned to recurring tasks ensures the following tasks are completed to help minimize technical debt.
The following tasks have tests that must be run locally on your workstation. To perform these tasks:
Look for uncompressed images.
Run the following commands in
gitlab-org/gitlabto check if any uncompressed images exist:
bundle exec rake pngquant:lint
If there are any results, create a new branch and compress the images with:
bundle exec rake pngquant:compress
Search for and remove expired redirect files.
Do a global search for product documentation
.mdfiles with the search term
This redirect file can be deleted afterto find the files that can now be deleted:
grep -ri "This redirect file can be deleted after" .
Delete any files that have a deletion date on or before the current date.
Note the filenames, redirect locations, and expiration dates of the expired redirect files, and then create an MR to remove those files (but don't assign it for merge yet).
Create an MR in
content/_data/redirects.yamlwith one redirect entry for each file you're removing. The expiry date should be nine months in the future. Keep the entries alphabetically sorted.
- from: /ee/path/to/old_file.html to: /ee/path/to/new_file.html remove_date: YYYY-MM-DD
Any redirect files that redirect to external docs (those starting with
https://) should be deleted, with nothing added to the
The path must start with the internal project directory (
/charts) and end with
from:redirect is an
index.htmlfile, add a duplicate entry for the
index.html). For example:
- from: /ee/user/project/operations/index.html to: /ee/operations/index.html remove_date: 2021-11-01 - from: /ee/user/project/operations/ to: /ee/operations/index.html remove_date: 2021-11-01
gitlab-docsMR 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-docsMR should be merged first, followed by the MRs in the other projects.
Be sure to
hsmith-watsonin Marketing so they can update any now-expired links on
The following tasks have tests that you can run from pipelines in the
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.
Click the Play button for the
Run TW chores jobsscheduled 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
Review the Kramdown build logs for warnings. Check the
compile_devjob log, and search for
kramdown warningmessages (which are usually caused by malformed Markdown). 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. Click Play on the jobs you want to run:
Check for unused images. Run the
test_unused_imagesjob, 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_linksjob, and fix as many of the links as time permits. Be aware that:
- You have to evaluate suggestions for new links, as the forwarded link may also be broken or may redirect again to another page.
- The forwarded link may include a trailing forward slash. While not required for most browsers, the trailing slash can help prevent errors.
- The forwarded link may not include section title links (anchors), such as
#section-title. You may need to add the
- Links may disappear, such as external software reaching end-of-life.
- Updated links may not provide the desired information. You may need to create an issue and assign to an SME to resolve these links.
- If you find that a failing link is actually valid, it may need to be excluded
from the link checker. This could be due to a website that needs authentication,
or a site with a server that returns a response the link checker sees as a failure.
Go to https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/nanoc.yaml
and add the link under
exclude:, following the pattern of the other links already there.
Check for trailing whitespace. Run the
test_EOL_whitespacejob to find all pages with lines that have trailing whitespace that isn't needed. To fix:
gitlabproject, run (with
yarn run markdownlint:no-trailing-spaces:fix doc
In the other projects, fix manually.
- Review the Kramdown build logs for warnings. Check the
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.