Remove the version-specific mentions in page

We support multiple types of markup. Our docs were overly specific
in a few places.

doc/administration/integration/plantuml.md

@@ -5,22 +5,94 @@ info: "To determine the technical writer assigned to the Stage/Group associated
 type: reference, howto
 ---
 
-# PlantUML & GitLab **(FREE)**
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8537) in GitLab 8.16.
+# PlantUML and GitLab **(FREE)**
 
 When [PlantUML](https://plantuml.com) integration is enabled and configured in
-GitLab you can create diagrams in AsciiDoc and Markdown documents
-created in snippets, wikis, and repositories.
+GitLab, you can create diagrams in snippets, wikis, and repositories. To set up
+the integration, you must:
+
+1. [Configure your PlantUML server](#configure-your-plantuml-server).
+1. [Configure local PlantUML access](#configure-local-plantuml-access).
+1. [Configure PlantUML security](#configure-plantuml-security).
+1. [Enable the integration](#enable-plantuml-integration).
+
+After completing the integration, PlantUML converts `plantuml`
+blocks to an HTML image tag, with the source pointing to the PlantUML instance. The PlantUML
+diagram delimiters `@startuml`/`@enduml` aren't required, as these are replaced
+by the `plantuml` block:
+
+- **Markdown**
 
-## PlantUML Server
+  ````markdown
+  ```plantuml
+  Bob -> Alice : hello
+  Alice -> Bob : hi
+  ```
+  ````
+
+- **AsciiDoc**
+
+  ```plaintext
+  [plantuml, format="png", id="myDiagram", width="200px"]
+  ----
+  Bob->Alice : hello
+  Alice -> Bob : hi
+  ----
+  ```
+
+- **reStructuredText**
+
+  ```plaintext
+  .. plantuml::
+     :caption: Caption with **bold** and *italic*
+
+     Bob -> Alice: hello
+     Alice -> Bob: hi
+  ```
+
+   Although you can use the `uml::` directive for compatibility with
+   [`sphinxcontrib-plantuml`](https://pypi.org/project/sphinxcontrib-plantuml/),
+   GitLab supports only the `caption` option.
 
-Before you can enable PlantUML in GitLab; set up your own PlantUML
-server to generate the diagrams.
+If the PlantUML server is correctly configured, these examples should render a
+diagram instead of the code block:
+
+```plantuml
+Bob -> Alice : hello
+Alice -> Bob : hi
+```
+
+Inside the block you can add any of the diagrams PlantUML supports, such as:
+
+- [Activity](https://plantuml.com/activity-diagram-legacy)
+- [Class](https://plantuml.com/class-diagram)
+- [Component](https://plantuml.com/component-diagram)
+- [Object](https://plantuml.com/object-diagram)
+- [Sequence](https://plantuml.com/sequence-diagram)
+- [State](https://plantuml.com/state-diagram)
+- [Use Case](https://plantuml.com/use-case-diagram)
+
+You can add parameters to block definitions:
+
+- `format`: Can be either `png` (default) or `svg`. Use `svg` with care, as it's
+  not supported by all browsers, and isn't supported by Markdown.
+- `id`: A CSS ID added to the diagram HTML tag.
+- `width`: Width attribute added to the image tag.
+- `height`: Height attribute added to the image tag.
+
+Markdown does not support any parameters, and always uses PNG format.
+
+## Configure your PlantUML server
+
+Before you can enable PlantUML in GitLab, set up your own PlantUML
+server to generate the diagrams:
+
+- [In Docker](#docker).
+- [In Debian/Ubuntu](#debianubuntu).
 
 ### Docker
 
-With Docker, you can just run a container like this:
+To run a PlantUML container in Docker, run this command:
 
 ```shell
 docker run -d --name plantuml -p 8080:8080 plantuml/plantuml-server:tomcat
@@ -29,8 +101,9 @@ docker run -d --name plantuml -p 8080:8080 plantuml/plantuml-server:tomcat
 The **PlantUML URL** is the hostname of the server running the container.
 
 When running GitLab in Docker, it must have access to the PlantUML container.
-You can achieve that by using [Docker Compose](https://docs.docker.com/compose/).
-A basic `docker-compose.yml` file could contain:
+To achieve that, use [Docker Compose](https://docs.docker.com/compose/).
+In this basic `docker-compose.yml` file, PlantUML is accessible to GitLab at the URL
+`http://plantuml:8080/`:
 
 ```yaml
 version: "3"
@@ -46,37 +119,32 @@ services:
     container_name: plantuml
 ```
 
-In this scenario, PlantUML is accessible to GitLab at the URL
-`http://plantuml:8080/`.
-
 ### Debian/Ubuntu
 
-You can also install and configure a PlantUML server in Debian/Ubuntu distributions using Tomcat.
+You can install and configure a PlantUML server in Debian/Ubuntu distributions
+using Tomcat:
 
-First you need to create a `plantuml.war` file from the source code:
+1. Run these commands to create a `plantuml.war` file from the source code:
 
-```shell
-sudo apt-get install graphviz openjdk-8-jdk git-core maven
-git clone https://github.com/plantuml/plantuml-server.git
-cd plantuml-server
-mvn package
-```
+   ```shell
+   sudo apt-get install graphviz openjdk-8-jdk git-core maven
+   git clone https://github.com/plantuml/plantuml-server.git
+   cd plantuml-server
+   mvn package
+   ```
 
-The above sequence of commands generates a `.war` file you can deploy with Tomcat:
+1. Deploy the `.war` file from the previous step with these commands:
 
-```shell
-sudo apt-get install tomcat8
-sudo cp target/plantuml.war /var/lib/tomcat8/webapps/plantuml.war
-sudo chown tomcat8:tomcat8 /var/lib/tomcat8/webapps/plantuml.war
-sudo service tomcat8 restart
-```
+   ```shell
+   sudo apt-get install tomcat8
+   sudo cp target/plantuml.war /var/lib/tomcat8/webapps/plantuml.war
+   sudo chown tomcat8:tomcat8 /var/lib/tomcat8/webapps/plantuml.war
+   sudo service tomcat8 restart
+   ```
 
-After the Tomcat service restarts, the PlantUML service is ready and
-listening for requests on port 8080:
-
-```plaintext
-http://localhost:8080/plantuml
-```
+The Tomcat service should restart. After the restart is complete, the
+PlantUML service is ready and listening for requests on port 8080:
+`http://localhost:8080/plantuml`
 
 To change these defaults, edit the `/etc/tomcat8/server.xml` file.
 
@@ -85,40 +153,44 @@ The default URL is different when using this approach. The Docker-based image
 makes the service available at the root URL, with no relative path. Adjust
 the configuration below accordingly.
 
-### Making local PlantUML accessible using custom GitLab setup
+## Configure local PlantUML access
 
-The PlantUML server runs locally on your server, so it is not accessible
-externally by default. As such, it is necessary to catch external PlantUML
-calls and redirect them to the local server.
+The PlantUML server runs locally on your server, so it can't be accessed
+externally by default. Your server must catch external PlantUML
+calls to `https://gitlab.example.com/-/plantuml/` and redirect them to the
+local PlantUML server. Depending on your setup, the URL is either of the
+following:
 
-The idea is to redirect each call to `https://gitlab.example.com/-/plantuml/`
-to the local PlantUML server `http://plantuml:8080/` or `http://localhost:8080/plantuml/`, depending on your setup.
+- `http://plantuml:8080/`
+- `http://localhost:8080/plantuml/`
 
-To enable the redirection, add the following line in `/etc/gitlab/gitlab.rb`:
+If you're running [GitLab with TLS](https://docs.gitlab.com/omnibus/settings/ssl.html)
+you must configure this redirection, because PlantUML uses the insecure HTTP protocol.
+Newer browsers such as [Google Chrome 86+](https://www.chromestatus.com/feature/4926989725073408)
+don't load insecure HTTP resources on pages served over HTTPS.
 
-```ruby
-# Docker deployment
-nginx['custom_gitlab_server_config'] = "location /-/plantuml/ { \n    proxy_cache off; \n    proxy_pass  http://plantuml:8080/; \n}\n"
+To enable this redirection:
 
-# Built from source
-nginx['custom_gitlab_server_config'] = "location /-/plantuml { \n rewrite ^/-/(plantuml.*) /$1 break;\n proxy_cache off; \n proxy_pass http://localhost:8080/plantuml; \n}\n"
-```
+1. Add the following line in `/etc/gitlab/gitlab.rb`, depending on your setup method:
 
-To activate the changes, run the following command:
+   ```ruby
+   # Docker deployment
+   nginx['custom_gitlab_server_config'] = "location /-/plantuml/ { \n    proxy_cache off; \n    proxy_pass  http://plantuml:8080/; \n}\n"
 
-```shell
-sudo gitlab-ctl reconfigure
-```
+   # Built from source
+   nginx['custom_gitlab_server_config'] = "location /-/plantuml { \n rewrite ^/-/(plantuml.*) /$1 break;\n proxy_cache off; \n proxy_pass http://localhost:8080/plantuml; \n}\n"
+   ```
 
-Note that the redirection through GitLab must be configured
-when running [GitLab with TLS](https://docs.gitlab.com/omnibus/settings/ssl.html)
-due to PlantUML's use of the insecure HTTP protocol. Newer browsers such
-as [Google Chrome 86+](https://www.chromestatus.com/feature/4926989725073408)
-do not load insecure HTTP resources on a page served over HTTPS.
+1. To activate the changes, run the following command:
+
+   ```shell
+   sudo gitlab-ctl reconfigure
+   ```
 
-### Security
+### Configure PlantUML security
 
-PlantUML has features that allow fetching network resources.
+PlantUML has features that allow fetching network resources. If you self-host the
+PlantUML server, put network controls in place to isolate it.
 
 ```plaintext
 @startuml
@@ -129,98 +201,29 @@ stop;
 @enduml
 ```
 
-**If you self-host the PlantUML server, network controls should be put in place to isolate it.**
+## Enable PlantUML integration
 
-## GitLab
+After configuring your local PlantUML server, you're ready to enable the PlantUML integration:
 
-You need to enable PlantUML integration from Settings under Admin Area. To do
-that, sign in with an Administrator account, and then do following:
-
-1. In GitLab, go to **Admin Area > Settings > General**.
-1. Expand the **PlantUML** section.
+1. Sign in to GitLab as an [Administrator](../../user/permissions.md) user.
+1. In the top menu, click **{admin}** **Admin Area**.
+1. In the left sidebar, go to **Settings > General** and expand the **PlantUML** section.
 1. Select the **Enable PlantUML** check box.
-1. Set the PlantUML instance as `https://gitlab.example.com/-/plantuml/`.
-
-NOTE:
-If you are using a PlantUML server running v1.2020.9 and
-above (for example, [plantuml.com](https://plantuml.com)), set the `PLANTUML_ENCODING`
-environment variable to enable the `deflate` compression. On Omnibus GitLab,
-this can be set in `/etc/gitlab.rb`:
-
-```ruby
-gitlab_rails['env'] = { 'PLANTUML_ENCODING' => 'deflate' }
-```
-
-From GitLab 13.1 and later, PlantUML integration now
-[requires a header prefix in the URL](https://github.com/plantuml/plantuml/issues/117#issuecomment-6235450160)
-to distinguish different encoding types.
-
-## Creating Diagrams
-
-With PlantUML integration enabled and configured, we can start adding diagrams to
-our AsciiDoc snippets, wikis, and repositories using delimited blocks:
-
-- **Markdown**
-
-  ````markdown
-  ```plantuml
-  Bob -> Alice : hello
-  Alice -> Bob : hi
-  ```
-  ````
-
-- **AsciiDoc**
-
-  ```plaintext
-  [plantuml, format="png", id="myDiagram", width="200px"]
-  ----
-  Bob->Alice : hello
-  Alice -> Bob : hi
-  ----
-  ```
+1. Set the PlantUML instance as `https://gitlab.example.com/-/plantuml/`,
+   and click **Save changes**.
 
-- **reStructuredText**
+Depending on your PlantUML and GitLab version numbers, you may also need to take
+these steps:
 
-  ```plaintext
-  .. plantuml::
-     :caption: Caption with **bold** and *italic*
+- For PlantUML servers running v1.2020.9 and above, such as [plantuml.com](https://plantuml.com),
+  you must set the `PLANTUML_ENCODING` environment variable to enable the `deflate`
+  compression. In Omnibus GitLab, you can set this value in `/etc/gitlab.rb` with
+  this command:
 
-     Bob -> Alice: hello
-     Alice -> Bob: hi
+  ```ruby
+   gitlab_rails['env'] = { 'PLANTUML_ENCODING' => 'deflate' }
    ```
 
-   You can also use the `uml::` directive for compatibility with
-   [`sphinxcontrib-plantuml`](https://pypi.org/project/sphinxcontrib-plantuml/),
-   but GitLab only supports the `caption` option.
-
-The above blocks are converted to an HTML image tag with source pointing to the
-PlantUML instance. If the PlantUML server is correctly configured, this should
-render a nice diagram instead of the block:
-
-```plantuml
-Bob -> Alice : hello
-Alice -> Bob : hi
-```
-
-Inside the block you can add any of the diagrams PlantUML supports, such as:
-
-- [Sequence](https://plantuml.com/sequence-diagram)
-- [Use Case](https://plantuml.com/use-case-diagram)
-- [Class](https://plantuml.com/class-diagram)
-- [Activity](https://plantuml.com/activity-diagram-legacy)
-- [Component](https://plantuml.com/component-diagram)
-- [State](https://plantuml.com/state-diagram),
-- [Object](https://plantuml.com/object-diagram)
-
-You do not need to use the PlantUML
-diagram delimiters `@startuml`/`@enduml`, as these are replaced by the AsciiDoc `plantuml` block.
-
-Some parameters can be added to the AsciiDoc block definition:
-
-- `format`: Can be either `png` or `svg`. Note that `svg` is not supported by
-  all browsers so use with care. The default is `png`.
-- `id`: A CSS ID added to the diagram HTML tag.
-- `width`: Width attribute added to the image tag.
-- `height`: Height attribute added to the image tag.
-
-Markdown does not support any parameters and always uses PNG format.
+- For GitLab versions 13.1 and later, PlantUML integration now
+  [requires a header prefix in the URL](https://github.com/plantuml/plantuml/issues/117#issuecomment-6235450160)
+  to distinguish different encoding types.

doc/user/admin_area/settings/index.md

@@ -35,7 +35,7 @@ Access the default page for admin area settings by navigating to **Admin Area >
 | ------ | ----------- |
 | [Elasticsearch](../../../integration/elasticsearch.md#enabling-advanced-search) | Elasticsearch integration. Elasticsearch AWS IAM. |
 | [Kroki](../../../administration/integration/kroki.md#enable-kroki-in-gitlab) | Allow rendering of diagrams in AsciiDoc and Markdown documents using [kroki.io](https://kroki.io). |
-| [PlantUML](../../../administration/integration/plantuml.md#gitlab) | Allow rendering of PlantUML diagrams in AsciiDoc and Markdown documents. |
+| [PlantUML](../../../administration/integration/plantuml.md) | Allow rendering of PlantUML diagrams in documents. |
 | [Slack application](../../../user/project/integrations/gitlab_slack_application.md#configuration) **(FREE SAAS)** | Slack integration allows you to interact with GitLab via slash commands in a chat window. This option is only available on GitLab.com, though it may be [available for self-managed instances in the future](https://gitlab.com/gitlab-org/gitlab/-/issues/28164). |
 | [Third party offers](third_party_offers.md) | Control the display of third party offers. |
 | [Snowplow](../../../development/snowplow.md) | Configure the Snowplow integration. |