Merge branch 'sselhorn-master-patch-63513' into 'master'

A few edits to help set the context

See merge request gitlab-org/gitlab!80534

doc/administration/docs_self_host.md

@@ -4,77 +4,69 @@ group: Distribution
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
 ---
 
-# How to self-host the docs site **(FREE SELF)**
-
-If you have a self-managed instance of GitLab, you may not be able to access the
-product documentation as hosted on `docs.gitlab.com` from your GitLab instance.
-
-Be aware of the following items if you self-host the product documentation:
-
-- You must host the product documentation site under a subdirectory that matches
-  your installed GitLab version (for example, `14.5/`). The
-  [Docker images](https://gitlab.com/gitlab-org/gitlab-docs/container_registry/631635)
-  hosted by the GitLab Docs team provide this by default. We use a
-  [script](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/2995d1378175803b22fb8806ba77adf63e79f32c/scripts/normalize-links.sh#L28-82)
-  to normalize the links and prefix them with the respective version.
-- The version dropdown will display additional versions that don't exist, selecting
-  those versions will display a 404 Not Found page.
-- Results when using the search box will display results from `docs.gitlab.com`
-  and not the local documentation.
-- When you use the Docker images to serve the product documentation site, by
-  default the landing page redirects to the respective version (for example, `/14.5/`),
-  which causes the landing page <https://docs.gitlab.com> to not be displayed.
+# How to host the GitLab product documentation **(FREE SELF)**
+
+If you are not able to access the GitLab product documentation at `docs.gitlab.com`,
+you can host the documentation yourself instead.
 
 ## Documentation self-hosting options
 
-You can self-host the GitLab product documentation locally using one of these
-methods:
+To host the GitLab product documentation, you can use:
 
-- Docker
+- A Docker container
 - GitLab Pages
-- From your own webserver
+- Your own web server
+
+After you create a website by using one of these methods, you redirect the UI links
+in the product to point to your website. 
 
-The examples on this page are based on GitLab 14.5.
+NOTE:
+The website you create must be hosted under a subdirectory that matches
+your installed GitLab version (for example, `14.5/`). The
+[Docker images](https://gitlab.com/gitlab-org/gitlab-docs/container_registry/631635)
+use this version by default.
+
+The following examples use GitLab 14.5.
 
 ### Self-host the product documentation with Docker
 
-The Docker images use a built-in webserver listening on port `4000`, so you need
-to expose that.
+You can run the GitLab product documentation website in a Docker container:
 
-In the server that you host GitLab, or any other server that your GitLab instance
-can talk to, you can use Docker to pull the docs site:
+1. Expose port `4000`. The Docker image uses this port for the web server.
+1. On the server where you host GitLab, or on any other server that your GitLab instance
+   can communicate with, pull the docs site:
 
-```shell
-docker run -it --rm -p 4000:4000 registry.gitlab.com/gitlab-org/gitlab-docs:14.5
-```
+   ```shell
+   docker run -it --rm -p 4000:4000 registry.gitlab.com/gitlab-org/gitlab-docs:14.5
+   ```
 
-If you use [Docker compose](../install/docker.md#install-gitlab-using-docker-compose)
-to host your GitLab instance, add the following to `docker-compose.yaml`:
-
-```yaml
-version: '3.6'
-services:
-  docs:
-    image: registry.gitlab.com/gitlab-org/gitlab-docs:14.5
-    hostname: 'https://gitlab.example.com'
-    ports:
-      - '4000:4000'
-```
+   If you host your GitLab instance using [Docker compose](../install/docker.md#install-gitlab-using-docker-compose),
+   add the following to `docker-compose.yaml`:
+
+   ```yaml
+   version: '3.6'
+   services:
+     docs:
+       image: registry.gitlab.com/gitlab-org/gitlab-docs:14.5
+       hostname: 'https://gitlab.example.com'
+       ports:
+         - '4000:4000'
+   ```
 
 ### Self-host the product documentation with GitLab Pages
 
-You use GitLab Pages to host the GitLab product documentation locally.
+You can use GitLab Pages to host the GitLab product documentation.
 
 Prerequisite:
 
-- The Pages site URL must not use a subfolder. Due to the nature of how the docs
+- Ensure the Pages site URL does not use a subfolder. Because of how the docs
   site is pre-compiled, the CSS and JavaScript files are relative to the
   main domain or subdomain. For example, URLs like `https://example.com/docs/`
   are not supported.
 
 To host the product documentation site with GitLab Pages:
 
-1. [Create a new blank project](../user/project/working_with_projects.md#create-a-blank-project).
+1. [Create a blank project](../user/project/working_with_projects.md#create-a-blank-project).
 1. Create a new or edit your existing `.gitlab-ci.yml` file, and add the following
    `pages` job, while ensuring the version is the same as your GitLab installation:
 
@@ -97,13 +89,13 @@ To host the product documentation site with GitLab Pages:
    | [Project website](../user/project/pages/getting_started_part_one.md#project-website-examples) | Not supported | Supported |
    | [User or group website](../user/project/pages/getting_started_part_one.md#user-and-group-website-examples) | Supported | Supported |
 
-### Self-host the product documentation on your own webserver
+### Self-host the product documentation on your own web server
 
-Because the product documentation site is static, you can grab the directory from
-the container (in `/usr/share/nginx/html`) and use your own web server to host
-it wherever you want.
+Because the product documentation site is static, from the container, you can take the contents
+of `/usr/share/nginx/html` and use your own web server to host
+the docs wherever you want.
 
-Use the following commands, and replace `<destination>` with the directory where the
+Run the following commands, replacing `<destination>` with the directory where the
 documentation files will be copied to:
 
 ```shell
@@ -114,18 +106,30 @@ docker rm -f gitlab-docs
 
 ## Redirect the `/help` links to the new docs page
 
-After your local product documentation site is running, [redirect the help
-links](../user/admin_area/settings/help_page.md#redirect-help-pages) in the GitLab
-application to your local site.
+After your local product documentation site is running,
+[redirect the help links](../user/admin_area/settings/help_page.md#redirect-help-pages)
+in the GitLab application to your local site.
 
 Be sure to use the fully qualified domain name as the docs URL. For example, if you
 used the [Docker method](#self-host-the-product-documentation-with-docker), enter `http://0.0.0.0:4000`.
 
-You don't need to append the version, as GitLab will detect it and append it to
-any documentation URL requests, as needed. For example, if your GitLab version is
-14.5, the GitLab Docs URL becomes `http://0.0.0.0:4000/14.5/`. The link
-inside GitLab displays as `<instance_url>/help/user/admin_area/settings/help_page#destination-requirements`,
-but when you select it, you are redirected to
+You don't need to append the version. GitLab detects it and appends it to
+documentation URL requests as needed. For example, if your GitLab version is
+14.5:
+
+- The GitLab Docs URL becomes `http://0.0.0.0:4000/14.5/`.
+- The link in GitLab displays as `<instance_url>/help/user/admin_area/settings/help_page#destination-requirements`.
+- When you select the link, you are redirected to
 `http://0.0.0.0:4000/14.5/ee/user/admin_area/settings/help_page/#destination-requirements`.
 
 To test the setting, select a **Learn more** link within the GitLab application.
+
+## Known issues
+
+If you self-host the product documentation:
+
+- The version dropdown displays additional versions that don't exist. Selecting
+  these versions displays a `404 Not Found` page.
+- The search displays results from `docs.gitlab.com` and not the local site.
+- By default, the landing page redirects to the
+  respective version (for example, `/14.5/`). This causes the landing page <https://docs.gitlab.com> to not be displayed.