Copyedit the maven packages repo docs

doc/administration/maven_packages.md

 # GitLab private Maven repository administration
 
 > **Notes:**
-> - [Introduced][ee-5811] in GitLab 11.3.
-> - This document is about the admin guide. Learn how to use GitLab Maven 
->   repository from [user documentation](../user/project/maven_packages.md).
+- [Introduced][ee-5811] in GitLab 11.3.
+- This document is about the admin guide. Learn how to use GitLab Maven
+  repository from [user documentation](../user/project/maven_packages.md).
 
-When enabled, every project in GitLab will have its own space to store Maven packages.
+When enabled, every project in GitLab will have its own space to store
+[Maven](https://maven.apache.org/) packages.
 
-## Enable the Maven repository
+## Enabling the Maven repository
+
+NOTE: **Note:**
+Once enabled, newly created projects will have the Packages feature enabled by
+default. Existing projects will need to
+[explicitly enabled it](../user/project/maven_packages.md#enabling-the-packages-repository).
 
 **Omnibus GitLab installations**
 
@@ -23,21 +29,15 @@ When enabled, every project in GitLab will have its own space to store Maven pac
 
 If you have installed GitLab from source:
 
-1. After the installation is complete, you will have to configure the `packages` 
-   section in `gitlab.yml` in order to enable it.
-
-The contents of `gitlab.yml` are:
-
-```
-packages:
-  enabled: true
-```
-
-where:
+1. After the installation is complete, you will have to configure the `packages`
+   section in `config/gitlab.yml`. Set to `true` to enable it:
 
-| Parameter | Description |
-| --------- | ----------- |
-| `enabled` | `true` or `false`. Enables the packages repository in GitLab. By default this is `false`. |
+      ```yaml
+      packages:
+        enabled: true
+      ```
+1. [Restart GitLab] for the changes to take effect.
 
 [reconfigure gitlab]: restart_gitlab.md#omnibus-gitlab-reconfigure "How to reconfigure Omnibus GitLab"
+[restart gitlab]: restart_gitlab.md#omnibus-gitlab-reconfigure "How to reconfigure Omnibus GitLab"
 [ee-5811]: https://gitlab.com/gitlab-org/gitlab-ee/issues/5811

doc/user/project/maven_packages.md

-# GitLab Maven Packages repository
+# GitLab Maven Packages repository **[PREMIUM]**
 
-## Configure project to use GitLab Maven Repository URL
+> Introduced in [GitLab Premium](https://about.gitlab.com/pricing/) 11.3.
 
-To download packages from GitLab, you need `repository` section in your `pom.xml`.
+With the GitLab [Maven](https://maven.apache.org) Packages repository, every
+project can have its own space to store its Maven artifacts.
+
+## Enabling the Packages repository
+
+NOTE: **Note:**
+This option is available only if your GitLab administrator has
+[enabled the Packages repository](../../administration/maven_packages.md).
+
+In order to use the GitLab Maven Packages repository, you must enable the
+general Packages repository. To enable (or disable) it:
+
+1. Navigate to your project's **Settings > General > Permissions**.
+1. Find the "Packages" feature and enable it.
+1. Click on **Save changes** for the changes to take effect.
+
+You should then be able to see the **Packages** section on the left sidebar.
+Next, you must configure your project to authorize with the Maven repository.
+
+## Authorizing with the Maven repository
+
+If a project is private or you want to upload Maven artifacts to GitLab,
+credentials will need to be provided for authorization:
+
+1. Create a new [personal access token](../profile/personal_access_tokens.md)
+   with the `api` scope.
+1. Add a corresponding section to your
+   [`settings.xml`](https://maven.apache.org/settings.html) file:
+
+    ```xml
+    <settings>
+      <servers>
+        <server>
+          <id>gitlab-maven</id>
+          <configuration>
+            <httpHeaders>
+              <property>
+                <name>Private-Token</name>
+                <value>REPLACE_WITH_YOUR_PERSONAL_ACCESS_TOKEN</value>
+              </property>
+            </httpHeaders>
+          </configuration>
+        </server>
+      </servers>
+    </settings>
+    ```
+
+You should now be able to upload Maven artifacts to your project.
+
+## Configuring your project to use the GitLab Maven repository URL
+
+To download packages from GitLab, you need a `repository` section in your
+`pom.xml` file:
 
 ```xml
 <repositories>
@@ -13,10 +65,15 @@ To download packages from GitLab, you need `repository` section in your `pom.xml
 </repositories>
 ```
 
-To upload packages to GitLab, you need a `distributionManagement` section in your `pom.xml`.
+Similarly, to upload packages to GitLab, you need a `distributionManagement`
+section in your `pom.xml` file:
 
 ```xml
 <distributionManagement>
+  <repository>
+    <id>gitlab-maven</id>
+    <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url>
+  </repository>
   <snapshotRepository>
     <id>gitlab-maven</id>
     <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url>
@@ -24,74 +81,61 @@ To upload packages to GitLab, you need a `distributionManagement` section in you
 </distributionManagement>
 ```
 
-In both examples, replace `PROJECT_ID` with your project ID. 
-If you have a private GitLab installation, replace `gitlab.com` with your domain name.
-
-## Configure repository access
-
-If a project is private, credentials will need to be provided for authorization.
-The preferred way to do this, is by using a [personal access tokens][pat].
-You can add a corresponding section to your `settings.xml` file:
-
-
-```xml
-<settings>
-  <servers>
-    <server>
-      <id>gitlab-maven</id>
-      <configuration>
-        <httpHeaders>
-          <property>
-            <name>Private-Token</name>
-            <value>REPLACE_WITH_YOUR_PRIVATE_TOKEN</value>
-          </property>
-        </httpHeaders>
-      </configuration>
-    </server>
-  </servers>
-</settings>
-```  
-
-## Create maven packages with GitLab CI
-
-Once you have your repository configured to use GitLab Maven Packages repository, 
-you can configure GitLab CI to build new packages automatically. The example below 
-shows you how to create a new package each time the master branch is updated.
-
-1\. Create a `ci_settings.xml` file specially for GitLab CI and put it into your repository. 
-Add server section there with same id as you used for GitLab repository in your `pom.xml` file. 
-For example, in our case its `gitlab-maven`.
-
-```xml
-<settings xmlns="http://maven.apache.org/SETTINGS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd">
-  <servers>
-    <server>
-      <id>gitlab-maven</id>
-      <configuration>
-        <httpHeaders>
-          <property>
-            <name>Job-Token</name>
-            <value>CI_JOB_TOKEN</value>
-          </property>
-        </httpHeaders>
-      </configuration>
-    </server>
-  </servers>
-</settings>
-```
-
-2\. Add `deploy` section to your `.gitlab-ci.yml` file.
-
-```
-deploy:
-  script:
-    - 'cp ci_settings.xml /root/.m2/settings.xml'
-    - 'sed -i "s/CI_JOB_TOKEN/${CI_JOB_TOKEN}/g" /root/.m2/settings.xml'
-    - 'mvn deploy'
-  only:
-    - master
-  image: maven:3.3.9-jdk-8
-```
-
-[pat]: ../profile/personal_access_tokens.md
+The `id` must be the same with what you
+[defined in `settings.xml`](#authorizing-with-the-maven-repository).
+
+In both examples, replace `PROJECT_ID` with your project ID which can be found
+on the home page of your project.
+
+If you have a private GitLab installation, replace `gitlab.com` with your
+domain name.
+
+## Creating maven packages with GitLab CI/CD
+
+Once you have your repository configured to use the GitLab Maven Packages repository,
+you can configure GitLab CI/CD to build new packages automatically. The example below
+shows how to create a new package each time the `master` branch is updated:
+
+1. Create a `ci_settings.xml` file that will serve as Maven's `settings.xml` file.
+   Add the server section with the same id you defined in your `pom.xml` file.
+   For example, in our case it's `gitlab-maven`:
+
+    ```xml
+    <settings xmlns="http://maven.apache.org/SETTINGS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+      xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd">
+      <servers>
+        <server>
+          <id>gitlab-maven</id>
+          <configuration>
+            <httpHeaders>
+              <property>
+                <name>Job-Token</name>
+                <value>CI_JOB_TOKEN</value>
+              </property>
+            </httpHeaders>
+          </configuration>
+        </server>
+      </servers>
+    </settings>
+    ```
+
+1. Add a `deploy` job to your `.gitlab-ci.yml` file:
+
+    ```yaml
+    deploy:
+      image: maven:3.3.9-jdk-8
+      script:
+        - 'cp ci_settings.xml /root/.m2/settings.xml'
+        - 'sed -i "s/CI_JOB_TOKEN/${CI_JOB_TOKEN}/g" /root/.m2/settings.xml'
+        - 'mvn deploy'
+      only:
+        - master
+    ```
+
+1. Push those files to your repository.
+
+The next time the `deploy` job runs, it will copy `ci_settings.xml` to the
+user's home location (in this case the user is `root` since it runs in a
+Docker container), and `sed` will replace the placeholder `CI_JOB_TOKEN`
+value with the contents of the actual [`CI_JOB_TOKEN`
+environment variable](../../ci/variables/README.md#predefined-variables-environment-variables).