Copyedit Registry user docs

3 files changed, 56 insertions, 27 deletions

diff --git a/doc/container_registry/README.md b/doc/container_registry/README.md
index 5af47f7120d..4df24ef13cc 100644
--- a/doc/container_registry/README.md
+++ b/doc/container_registry/README.md
@@ -3,33 +3,48 @@
 > **Note:**
 This feature was [introduced][ce-4040] in GitLab 8.8.
 
+> **Note:**
+This document is about the user guide. To learn how to enable GitLab Container
+Registry across your GitLab instance, visit the
+[administrator documentation](../administration/container_registry.md).
+
 With the Docker Container Registry integrated into GitLab, every project can
 have its own space to store its Docker images.
 
 You can read more about Docker Registry at https://docs.docker.com/registry/introduction/.
 
-You can read more about administering GitLab Container Registry on [GitLab Container Registry Administration](../administration/container_registry.md)
-
 ---
 
-## Start using Container Registry
+## Enable the Container Registry for your project
 
-1. First ask your system administrator to enable GitLab Container Registry following the [administration documentation](../administration/container_registry.md).
+1. First, ask your system administrator to enable GitLab Container Registry
+   following the [administration documentation](../administration/container_registry.md).
+   If you are using GitLab.com, this is enabled by default so you can start using
+   the Registry immediately.
 
-2. Go to project settings and enable `Container Registry` feature on your project:
+1. Go to your project's settings and enable the **Container Registry** feature
+   on your project. For new projects this might be enabled by default. For
+   existing projects you will have to explicitly enable it.
+
+    ![Enable Container Registry](img/project_feature.png)
+
+## Build and push images
 
-![](project_feature.png)
+After you save your project's settings, you should see a new link in the
+sidebar called **Container Registry**. Following this link will get you to
+your project's Registry panel where you can see how to login to the Container
+Registry using your GitLab credentials.
 
-3. Login to Container Registry with your credentials:
+For example if the Registry's URL is `registry.example.com`, the you should be
+able to login with:
 
 ```
 docker login registry.example.com
 ```
 
-## Build and push images
-
-Your registry is accessible under address configured via `registry_external_url`.
-To start using it you need to first build and publish images:
+Building and publishing images should be a straightforward process. Just make
+sure that you are using the Registry URL with the namespace and project name
+that is hosted on GitLab:
 
 ```
 docker build -t registry.example.com/group/project .
@@ -38,18 +53,25 @@ docker push registry.example.com/group/project
 
 ## Use images from GitLab Container Registry
 
-To download and run container from images hosted in GitLab Container Registry use `docker run`:
+To download and run a container from images hosted in GitLab Container Registry,
+use `docker run`:
 
 ```
 docker run [options] registry.example.com/group/project [arguments]
 ```
 
-## Control Container Registry from GitLab
+For more information on running Docker containers, visit the
+[Docker documentation][docker-docs].
+
+## Control Container Registry from within GitLab
 
-GitLab offers simple Container Registry management. Go to your project and click **Container Registry**.
-This view will show you all tags in your repository and will easily allow you to delete them.
+GitLab offers a simple Container Registry management panel. Go to your project
+and click **Container Registry** in the left sidebar.
 
-![](container_registry.png)
+This view will show you all tags in your project and will easily allow you to
+delete them.
+
+![Container Registry panel](img/container_registry.png)
 
 ## Build and push images using GitLab CI
 
@@ -57,10 +79,10 @@ This view will show you all tags in your repository and will easily allow you to
 This feature requires GitLab 8.8 and GitLab Runner 1.2.
 
 Make sure that your GitLab Runner is configured to allow building docker images.
-You have to check the [Using Docker Build](../../ci/docker/using_docker_build.md).
+You have to check the [Using Docker Build documentation](../../ci/docker/using_docker_build.md).
 
-You can use [docker:dind](https://hub.docker.com/_/docker/) to build your images. 
-This is how the `.gitlab-ci.yml` looks like:
+You can use [docker:dind](https://hub.docker.com/_/docker/) to build your images,
+and this is how `.gitlab-ci.yml` should look like:
 
 ```
  build_image:
@@ -69,16 +91,23 @@ This is how the `.gitlab-ci.yml` looks like:
    - docker:dind
    stage: build
    script:
-     - docker login -u gitlab-ci-token -p $CI_BUILD_TOKEN registry.gitlab.com
-     - docker build -t registry.gitlab.com/group/project:latest .
-     - docker push registry.gitlab.com/group/project:latest
+     - docker login -u gitlab-ci-token -p $CI_BUILD_TOKEN registry.example.com
+     - docker build -t registry.example.com/group/project:latest .
+     - docker push registry.example.com/group/project:latest
 ```
 
-You have to use special credentials `gitlab-ci-token` with password stored in `$CI_BUILD_TOKEN` in order to push to registry connected to your project.
-This allows you to automated building and deployment of your images.
+You have to use the credentials of the special `gitlab-ci-token` user with its
+password stored in `$CI_BUILD_TOKEN` in order to push to the Registry connected
+to your project. This allows you to automated building and deployment of your
+Docker images.
 
 ## Limitations
 
-In order to use container image from private project as an `image:` in your `.gitlab-ci.yml` you have to follow
-[Using a private Docker Registry](https://gitlab.com/gitlab-org/gitlab-ci-multi-runner/blob/master/docs/configuration/advanced-configuration.md#using-a-private-docker-registry).
-This workflow will be simplified in the future.
+In order to use a container image from your private project as an `image:` in
+your `.gitlab-ci.yml`, you have to follow the
+[Using a private Docker Registry][private-docker]
+documentation. This workflow will be simplified in the future.
+
+[ce-4040]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4040
+[docker-docs]: https://docs.docker.com/engine/userguide/intro/
+[private-docker]: https://gitlab.com/gitlab-org/gitlab-ci-multi-runner/blob/master/docs/configuration/advanced-configuration.md#using-a-private-docker-registry
diff --git a/doc/container_registry/container_registry.png b/doc/container_registry/img/container_registry.png
index e9505a73b40..e9505a73b40 100644
--- a/doc/container_registry/container_registry.png
+++ b/doc/container_registry/img/container_registry.png
diff --git a/doc/container_registry/project_feature.png b/doc/container_registry/img/project_feature.png
index 57a73d253c0..57a73d253c0 100644
--- a/doc/container_registry/project_feature.png
+++ b/doc/container_registry/img/project_feature.png