Docs: Use Markdownlint rule MD059 - Link text should be descriptive

Problem to solve

A recent update to markdownlint https://github.com/DavidAnson/markdownlint/blob/main/CHANGELOG.md#0380 introduced a new default rule: https://github.com/DavidAnson/markdownlint/blob/main/doc/md059.md.

To continue to move to later versions of markdownlint, we must decide to use the new rule, or turn it off.

Further details

We currently handle link text rules with a warning-level rule in Vale: https://gitlab.com/gitlab-org/gitlab/-/blob/e8739586bfabf0d297da64aa1995bc1b55374a2c/doc/.vale/gitlab_base/MeaningfulLinkWords.yml.

The markdownlint rule, by default, finds more instances of non-descriptive link text, and can be customized to include everything the Vale rule finds, and more. Of course, the Vale rule can be updated to find more non-descriptive link text also.

The main difference is that all markdownlint rules are error-level; they always break a pipeline. If we decide to use the markdownlint rule, we must decide to elevate the severity of this section of the style guide: https://docs.gitlab.com/development/documentation/styleguide/#descriptive-text-rather-than-here (permalink: https://gitlab.com/gitlab-org/gitlab/-/blob/e7715b94252d3e83710c94b65cf4f6b351f82d28/doc/development/documentation/styleguide/_index.md#L1019).

Proposal

I propose we switch from using the warning-level Vale rule to the error-level markdownlint rule for these reasons:

  • The markdownlint rule is simpler to configure and extend. The configuration is easier to locate for folks looking for it.
  • Most, if not all, Technical Writers would edit out violations of this rule if someone attempted to add a violation. There is essential no debate about whether descriptive link text is far better than non-descriptive link text.
  • The fixes for existing violations of the new markdownlint rule are trivial and there aren't too many.

To assess how many existing violations are in the gitlab project (by far the largest source of documentation):

  1. In your checkout of gitlab, modify .tool-versions.
  2. Update the specified version of markdownlint-cli2 to latest current: https://github.com/DavidAnson/markdownlint-cli2/tags (markdownlint-cli2 incorporates markdownlint).
  3. Run markdownlint-cli2 --help in your checkout of gitlab and make sure the version is expected. You might need to run it a couple of times so that mise has picked it up.
  4. Run markdownlint-cli2 'doc/**/*.md' and note the number of violations of MD059/descriptive-link-text.

At this point in time, there 24 violations.

Who can address the issue

For the decision, @fneill and @kpaizee.

For the work to address the violations, anyone, with the guidance of a Technical Writer, or a Technical Writer themselves.

CC @gitlab-org/technical-writing/tw-docops

Other links/references

Edited by 🤖 GitLab Bot 🤖