diff --git a/doc/source/admin/drivers/gerrit.rst b/doc/source/admin/drivers/gerrit.rst
index 6cd2f3d..0efb195 100644
--- a/doc/source/admin/drivers/gerrit.rst
+++ b/doc/source/admin/drivers/gerrit.rst
@@ -36,7 +36,11 @@
   The canonical hostname associated with the git repos on the Gerrit
   server.  Defaults to the value of **server**.  This is used to
   identify repos from this connection by name and in preparing repos
-  on the filesystem for use by jobs.
+  on the filesystem for use by jobs.  This only needs to be set in the
+  case where the canonical public location of the git repos is not the
+  same as the Gerrit server and it would be incorrect to refer to
+  those repos in configuration and build scripts using the Gerrit
+  server hostname.
   ``canonical_hostname=git.example.com``
 
 **port**
diff --git a/doc/source/admin/drivers/github.rst b/doc/source/admin/drivers/github.rst
index cc2a5c9..9aadf7f 100644
--- a/doc/source/admin/drivers/github.rst
+++ b/doc/source/admin/drivers/github.rst
@@ -46,6 +46,17 @@
   If not specified, defaults to ``github.com``
   ``git_host=github.myenterprise.com``
 
+**canonical_hostname**
+  The canonical hostname associated with the git repos on the GitHub
+  server.  Defaults to the value of **git_host**.  This is used to
+  identify repos from this connection by name and in preparing repos
+  on the filesystem for use by jobs.  This only needs to be set in the
+  case where the canonical public location of the git repos is not the
+  same as the GitHub server and it would be incorrect to refer to
+  those repos in configuration and build scripts using the GitHub
+  server hostname.
+  ``canonical_hostname=git.example.com``
+
 Trigger Configuration
 ---------------------
 GitHub webhook events can be configured as triggers.
diff --git a/doc/source/user/jobs.rst b/doc/source/user/jobs.rst
index ad26327..5637552 100644
--- a/doc/source/user/jobs.rst
+++ b/doc/source/user/jobs.rst
@@ -48,6 +48,19 @@
 Do not use any git remotes; the local repositories are guaranteed to
 be up to date.
 
+The repositories will be placed on the filesystem in directories
+corresponding with the canonical hostname of their source connection.
+For example::
+
+  work/src/git.example.com/project1
+  work/src/github.com/project2
+
+Is the layout that would be present for a job which included project1
+from the connection associated to git.example.com and project2 from
+GitHub.  This helps avoid collisions between projects with the same
+name, and some language environments, such as Go, expect repositories
+in this format.
+
 Note that these git repositories are located on the executor; in order
 to be useful to most kinds of jobs, they will need to be present on
 the test nodes.  The ``base`` job in the standard library contains a