Add a userguide to cover the uses of Hub before creating new repositories

Signed-off-by: Sven Dowideit <SvenDowideit@home.org.au>

docs/mkdocs.yml

@@ -75,7 +75,8 @@ pages:
 # Docker Hub docs:
 - ['docker-hub/index.md', 'Docker Hub', 'Docker Hub' ]
 - ['docker-hub/accounts.md', 'Docker Hub', 'Accounts']
-- ['docker-hub/repos.md', 'Docker Hub', 'Repositories']
+- ['docker-hub/userguide.md', 'Docker Hub', 'User Guide']
+- ['docker-hub/repos.md', 'Docker Hub', 'Your Repositories']
 - ['docker-hub/builds.md', 'Docker Hub', 'Automated Builds']
 - ['docker-hub/official_repos.md', 'Docker Hub', 'Official Repositories']
 

docs/sources/docker-hub/index.md

@@ -4,20 +4,29 @@ page_keywords: Docker, docker, registry, accounts, plans, Dockerfile, Docker Hub
 
 # Docker Hub
 
+The [Docker Hub](https://hub.docker.com) provides a cloud-based platform service
+for distributed applications, including container image distribution and change
+management, user and team collaboration, and lifecycle workflow automation.
+
 ![DockerHub](/docker-hub/hub-images/hub.png)
 
-## [Accounts](accounts/)
+## [Finding and pulling images](./userguide.md)
 
-[Learn how to create](accounts/) a [Docker Hub](https://hub.docker.com)
+Find out how to [use the Docker Hub](./userguide.md) to find and pull Docker
+images to run or build upon.
+
+## [Accounts](./accounts.md)
+
+[Learn how to create](./accounts.md) a Docker Hub
 account and manage your organizations and groups.
 
-## [Repositories](repos/)
+## [Your Repositories](./repos.md)
 
 Find out how to share your Docker images in [Docker Hub
-repositories](repos/) and how to store and manage private images.
+repositories](./repos.md) and how to store and manage private images.
 
-## [Automated builds](builds/)
+## [Automated builds](./builds.md)
 
 Learn how to automate your build and deploy pipeline with [Automated
-Builds](builds/)
+Builds](./builds.md)
 

docs/sources/docker-hub/repos.md

@@ -1,42 +1,37 @@
-page_title: Repositories and images on Docker Hub
-page_description: Repositories and images on Docker Hub
+page_title: Your Repositories on Docker Hub
+page_description: Your Repositories on Docker Hub
 page_keywords: Docker, docker, registry, accounts, plans, Dockerfile, Docker Hub, webhooks, docs, documentation
 
-# Repositories and images on Docker Hub
+# Your Hub repositories
+
+Docker Hub repositories make it possible for you to share images with co-workers,
+customers or the Docker community at large. If you're building your images internally,
+either on your own Docker daemon, or using your own Continuous integration services,
+you can push them to a Docker Hub repository that you add to your Docker Hub user or
+organization account.
+
+Alternativly, if the source code for your Docker image is on GitHub or Bitbucket,
+you can use an "Automated build" repository, which is built by the Docker Hub
+services. See the [automated builds documentation](./builds.md) to read about
+the extra functionality provided by those services.
 
 ![repositories](/docker-hub/hub-images/repos.png)
 
-## Searching for repositories and images
-
-You can `search` for all the publicly available repositories and images using
-Docker.
-
-    $ docker search ubuntu
-
-This will show you a list of the currently available repositories on the
-Docker Hub which match the provided keyword.
-
-If a repository is private it won't be listed on the repository search
-results. To see repository statuses, you can look at your [profile
-page](https://hub.docker.com) on [Docker Hub](https://hub.docker.com).
-
-## Repositories
-
 Your Docker Hub repositories have a number of useful features.
 
-### Stars
+## Stars
 
 Your repositories can be starred and you can star repositories in
 return. Stars are a way to show that you like a repository. They are
 also an easy way of bookmarking your favorites.
 
-### Comments
+## Comments
 
 You can interact with other members of the Docker community and maintainers by
 leaving comments on repositories. If you find any comments that are not
 appropriate, you can flag them for review.
 
-### Collaborators and their role
+## Collaborators and their role
 
 A collaborator is someone you want to give access to a private
 repository. Once designated, they can `push` and `pull` to your
@@ -48,24 +43,9 @@ private to public.
 > A collaborator cannot add other collaborators. Only the owner of
 > the repository has administrative access.
 
-You can also collaborate on Docker Hub with organizations and groups.
-You can read more about that [here](accounts/).
-
-## Official Repositories
-
-The Docker Hub contains a number of [Official
-Repositories](http://registry.hub.docker.com/official). These are
-certified repositories from vendors and contributors to Docker. They
-contain Docker images from vendors like Canonical, Oracle, and Red Hat
-that you can use to build applications and services.
-
-If you use Official Repositories you know you're using a supported,
-optimized and up-to-date image to power your applications.
-
-> **Note:**
-> If you would like to contribute an Official Repository for your
-> organization, see [Official Repositories on Docker
-> Hub](/docker-hub/official_repos) for more information.
+You can also assign more granular collaborator rights ("Read", "Write", or "Admin")
+on Docker Hub by using organizations and groups. For more information
+see the [accounts documentation](accounts/).
 
 ## Private repositories
 
@@ -100,8 +80,15 @@ Hub](https://registry.hub.docker.com/plans/) plan.
 
 ## Webhooks
 
-You can configure webhooks for your repositories on the Repository
-Settings page. A webhook is called only after a successful `push` is
+A webhook is an HTTP call-back triggered by a specific event.
+You can use a Hub repository webhook to notify people, services, and other
+applications after a new image is pushed to your repository (this also happens
+for Automated builds). For example, you can trigger an automated test or
+deployment to happen as soon as the image is available.
+
+To get started adding webhooks, go to the desired repository in the Hub,
+and click "Webhooks" under the "Settings" box.
+A webhook is called only after a successful `push` is
 made. The webhook calls are HTTP POST requests with a JSON payload
 similar to the example shown below.
 
@@ -137,13 +124,9 @@ similar to the example shown below.
 }
 ```
 
-Webhooks allow you to notify people, services and other applications of
-new updates to your images and repositories. To get started adding webhooks,
-go to the desired repository in the Hub, and click "Webhooks" under the "Settings"
-box.
+<TODO: does it tell you what tag was updated?>
 
-> **Note:** For testing, you can try an HTTP request tool like
-> [requestb.in](http://requestb.in/).
+For testing, you can try an HTTP request tool like [requestb.in](http://requestb.in/).
 
 > **Note**: The Docker Hub servers are currently in the IP range
 > `162.242.195.64 - 162.242.195.127`, so you can restrict your webhooks to
@@ -161,7 +144,7 @@ in your chain.
 The first webhook in a chain will be called after a successful push. Subsequent
 URLs will be contacted after the callback has been validated.
 
-#### Validating a callback
+### Validating a callback
 
 In order to validate a callback in a webhook chain, you need to
 
@@ -195,3 +178,10 @@ The following parameters are recognized in callback data:
       "context": "Continuous integration by Acme CI",
       "target_url": "http://ci.acme.com/results/afd339c1c3d27"
     }
+
+## Mark as unlisted
+
+By marking a repository as unlisted, you can create a publically pullable repository
+which will not be in the Hub or commandline search. This allows you to have a limited
+release, but does not restrict access to anyone that is told, or guesses the repository
+name.

docs/sources/docker-hub/userguide.md

@@ -0,0 +1,57 @@
+page_title: Docker Hub user guide
+page_description: Docker Hub user guide
+page_keywords: Docker, docker, registry, Docker Hub, docs, documentation
+
+# Using the Docker Hub
+
+Docker Hub is used to find and pull Docker images to run or build upon, and to
+distribute and build images for other users to use.
+
+![your profile](/docker-hub/hub-images/dashboard.png)
+
+## Finding repositories and images
+
+There are two ways you can search for public repositories and images available
+on the Docker Hub. You can use the "Search" tool on the Docker Hub website, or
+you can `search` for all the repositories and images using the Docker commandline
+tool:
+
+    $ docker search ubuntu
+
+Both will show you a list of the currently available public repositories on the
+Docker Hub which match the provided keyword.
+
+If a repository is private or marked as unlisted, it won't be in the repository
+search results. To see all the repositories you have access to and their statuses,
+you can look at your profile page on [Docker Hub](https://hub.docker.com).
+
+## Pulling, running and building images
+
+You can find more information on [working with Docker images](../userguide/dockerimages.md).
+
+## Official Repositories
+
+The Docker Hub contains a number of [Official
+Repositories](http://registry.hub.docker.com/official). These are
+certified repositories from vendors and contributors to Docker. They
+contain Docker images from vendors like Canonical, Oracle, and Red Hat
+that you can use to build applications and services.
+
+If you use Official Repositories you know you're using an optimized and
+up-to-date image to power your applications.
+
+> **Note:**
+> If you would like to contribute an Official Repository for your
+> organization, see [Official Repositories on Docker
+> Hub](/docker-hub/official_repos) for more information.
+
+## Building and shipping your own repositories and images
+
+The Docker Hub provides you and your team with a place to build and ship Docker images.
+
+Collections of Docker images are managed using repositories - 
+
+You can configure two types of repositories to manage on the Docker Hub:
+[Repositories](./repos.md), which allow you to push images to the Hub from your local Docker daemon,
+and [Automated Builds](./builds.md), which allow you to configure GitHub or Bitbucket to
+trigger the Hub to rebuild repositories when changes are made to the repository.