Merge branch 'axil-redirect-dev-guide' into 'master'

Consolidate the two methods of docs redirect

See merge request gitlab-org/gitlab!30613

doc/development/documentation/index.md

@@ -77,13 +77,24 @@ whether the move is necessary), and ensure that a technical writer reviews this
 change prior to merging.
 
 If you indeed need to change a document's location, do not remove the old
-document, but instead replace all of its content with a new line:
+document, but instead replace all of its content with the following:
 
 ```md
-This document was moved to [another location](path/to/new_doc.md).
+---
+redirect_to: '../path/to/file/index.md'
+---
+
+This document was moved to [another location](../path/to/file/index.md).
 ```
 
-where `path/to/new_doc.md` is the relative path to the root directory `doc/`.
+Where `../path/to/file/index.md` is usually the relative path to the old document.
+
+The `redirect_to` variable supports both full and relative URLs, for example
+`https://docs.gitlab.com/ee/path/to/file.html`, `../path/to/file.html`, `path/to/file.md`.
+It ensures that the redirect will work for <https://docs.gitlab.com> and any `*.md` paths
+will be compiled to `*.html`.
+The new line underneath the frontmatter informs the user that the document
+changed location and is useful for someone that browses that file from the repository.
 
 For example, if you move `doc/workflow/lfs/index.md` to
 `doc/administration/lfs.md`, then the steps would be:
@@ -92,12 +103,16 @@ For example, if you move `doc/workflow/lfs/index.md` to
 1. Replace the contents of `doc/workflow/lfs/index.md` with:
 
    ```md
+   ---
+   redirect_to: '../../administration/lfs.md'
+   ---
+
    This document was moved to [another location](../../administration/lfs.md).
    ```
 
 1. Find and replace any occurrences of the old location with the new one.
-   A quick way to find them is to use `git grep`. First go to the root directory
-   where you cloned the `gitlab` repository and then do:
+   A quick way to find them is to use `git grep` on the repository you changed
+   the file from:
 
    ```shell
    git grep -n "workflow/lfs/lfs_administration"
@@ -124,24 +139,6 @@ Things to note:
   built-in help page, that's why we omit it in `git grep`.
 - Use the checklist on the "Change documentation location" MR description template.
 
-### Alternative redirection method
-
-You can also replace the content
-of the old file with a frontmatter containing a redirect link:
-
-```yaml
----
-redirect_to: '../path/to/file/README.md'
----
-```
-
-It supports both full and relative URLs, e.g. `https://docs.gitlab.com/ee/path/to/file.html`, `../path/to/file.html`, `path/to/file.md`. Note that any `*.md` paths will be compiled to `*.html`.
-
-NOTE: **Note:**
-This redirection method will not provide a redirect fallback on GitLab `/help`. When using
-it, make sure to add a link to the new page on the doc, otherwise it's a dead end for users that
-land on the doc via `/help`.
-
 ### Redirections for pages with Disqus comments
 
 If the documentation page being relocated already has Disqus comments,