Update related documentation

Update the newly added documentation to be more precise and
fix the typos.

Add information about Project aliases into permissions doc.

3 files changed, 35 insertions, 16 deletions

diff --git a/doc/api/project_aliases.md b/doc/api/project_aliases.md
index 4456388c74f..20e4e844654 100644
--- a/doc/api/project_aliases.md
+++ b/doc/api/project_aliases.md
@@ -1,10 +1,12 @@
-# Project Aliases API
+# Project Aliases API **[PREMIUM ONLY]**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/3264) in GitLab 12.1.
 
 All methods require administrator authorization.
 
 ## List all project aliases
 
-Get a list of all project aliases
+Get a list of all project aliases:
 
 ```
 GET /project_aliases
@@ -33,7 +35,7 @@ Example response:
 
 ## Get project alias' details
 
-Get details of a project alias
+Get details of a project alias:
 
 ```
 GET /project_aliases/:name
@@ -57,9 +59,10 @@ Example response:
 }
 ```
 
-## Create an alias for a project
+## Create a project alias
 
-Add a new alias for a project. Reponds with a 201 when successful, 400 when there are validation errors (e.g. alias already exists).
+Add a new alias for a project. Responds with a 201 when successful,
+400 when there are validation errors (e.g. alias already exists):
 
 ```
 POST /project_aliases
@@ -67,7 +70,7 @@ POST /project_aliases
 
 | Attribute    | Type   | Required | Description                                   |
 |--------------|--------|----------|-----------------------------------------------|
-| `project_id` | string | yes      | The The ID or URL-encoded path of the project |
+| `project_id` | string | yes      | The ID or URL-encoded path of the project.    |
 | `name`       | string | yes      | The name of the alias. Must be unique.        |
 
 ```
@@ -84,9 +87,10 @@ Example response:
 }
 ```
 
-## Delete a project aliase
+## Delete a project alias
 
-Removes a project aliases. Respond with a 204 when project alias exists, 404 when it doesn't.
+Removes a project aliases. Responds with a 204 when project alias
+exists, 404 when it doesn't:
 
 ```
 DELETE /project_aliases/:name
diff --git a/doc/user/permissions.md b/doc/user/permissions.md
index 7af3d4a0ac3..03abef9fc62 100644
--- a/doc/user/permissions.md
+++ b/doc/user/permissions.md
@@ -365,3 +365,8 @@ for details about the pipelines security model.
 
 Since GitLab 8.15, LDAP user permissions can now be manually overridden by an admin user.
 Read through the documentation on [LDAP users permissions](../administration/auth/how_to_configure_ldap_gitlab_ee/index.html) to learn more.
+
+## Project aliases
+
+Project aliases can only be read, created and deleted by a GitLab administrator.
+Read through the documentation on [Project aliases](../user/project/index.md#project-aliases-premium-only) to learn more.
diff --git a/doc/user/project/index.md b/doc/user/project/index.md
index d9c35165ac8..2d39fdf8154 100644
--- a/doc/user/project/index.md
+++ b/doc/user/project/index.md
@@ -193,17 +193,27 @@ password <personal_access_token>
 To quickly access a project from the GitLab UI using the project ID,
 visit the `/projects/:id` URL in your browser or other tool accessing the project.
 
-## Project aliases
+## Project aliases **[PREMIUM ONLY]**
 
-Projects' repositories are usually cloned with a namespace and project name. It is
-also possible to clone them via a project alias. This feature is only available on Git over SSH.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/3264) in GitLab 12.1.
 
-A project alias can be created via API only by administrators. Follow the
-[Project Aliases API documentation](../../api/project_aliases.md) for more details.
+When migrating repositories to GitLab and they are being accessed by other systems,
+it's very useful to be able to access them using the same name especially when
+they are a lot. It reduces the risk of changing significant number of Git URLs in
+a large number of systems.
 
-Once an alias has been created for a project (e.g. gitlab-ce for gitlab-org/gitlab-ce),
-the repository can be cloned using the alias (e.g `git clone git@gitlab.com:gitlab-ce.git`
-instead of `git clone git@gitlab.com:gitlab-org/gitlab-ce.git`).
+GitLab provides a functionality to help with this. In GitLab, repositories are
+usually accessed with a namespace and project name. It is also possible to access
+them via a project alias. This feature is only available on Git over SSH.
+
+A project alias can be only created via API and only by GitLab administrators.
+Follow the [Project Aliases API documentation](../../api/project_aliases.md) for
+more details.
+
+Once an alias has been created for a project (e.g., an alias `gitlab-ce` for the
+project `https://gitlab.com/gitlab-org/gitlab-ce`), the repository can be cloned
+using the alias (e.g `git clone git@gitlab.com:gitlab-ce.git` instead of
+`git clone git@gitlab.com:gitlab-org/gitlab-ce.git`).
 
 ## Project APIs