--- a/taskcluster/docker/README.md
+++ b/taskcluster/docker/README.md
@@ -90,21 +90,24 @@ Example:
   image: {#docker_image}builder{/docker_image}
 
 Each image has a hash and a version, given by its `HASH` and `VERSION` files.
 When rebuilding a prebuilt image the `VERSION` should be bumped. Once a new
 version of the image has been built the `HASH` file should be updated with the
 hash of the image.
 
 The `HASH` file is the image hash as computed by docker, this is always on the
-format `sha256:<digest>`. In production images will be referenced by image hash.
-This mitigates attacks against the registry as well as simplifying validate of
-correctness. The `VERSION` file only serves to provide convenient names, such
-that old versions are easy to discover in the registry (and ensuring old
-versions aren't deleted by garbage-collection).
+format `sha256:<digest>`. Note that Docker produces a numbre of hashes in this
+format; the hash used in this context is the one returned from `docker push`.
+
+In production images will be referenced by image hash.  This mitigates attacks
+against the registry as well as simplifying validate of correctness. The
+`VERSION` file only serves to provide convenient names, such that old versions
+are easy to discover in the registry (and ensuring old versions aren't deleted
+by garbage-collection).
 
 This way, older tasks which were designed to run on an older version of the image
 can still be executed in taskcluster, while new tasks can use the new version.
 Further more, this mitigates attacks against the registry as docker will verify
 the image hash when loading the image.
 
 Each image also has a `REGISTRY`, defaulting to the `REGISTRY` in this directory,
 and specifying the image registry to which the completed image should be uploaded.

--- a/taskcluster/docs/docker-images.rst
+++ b/taskcluster/docs/docker-images.rst
@@ -3,16 +3,18 @@
 =============
 Docker Images
 =============
 
 TaskCluster Docker images are defined in the source directory under
 ``taskcluster/docker``. Each directory therein contains the name of an
 image used as part of the task graph.
 
+More information is available in the ``README.md`` file in that directory.
+
 Adding Extra Files to Images
 ============================
 
 Dockerfile syntax has been extended to allow *any* file from the
 source checkout to be added to the image build *context*. (Traditionally
 you can only ``ADD`` files from the same directory as the Dockerfile.)
 
 Simply add the following syntax as a comment in a Dockerfile::