incorporate minimalism feedback on distributing collections page (#75266) (#75302)

(cherry picked from commit 0e9d1ab1cc14e5d48e4811fba182eb7582d1050a)

Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>

4 files changed, 247 insertions, 140 deletions

diff --git a/docs/docsite/rst/dev_guide/developing_collections_distributing.rst b/docs/docsite/rst/dev_guide/developing_collections_distributing.rst
index edeffb5850..0d9c3b9398 100644
--- a/docs/docsite/rst/dev_guide/developing_collections_distributing.rst
+++ b/docs/docsite/rst/dev_guide/developing_collections_distributing.rst
@@ -4,66 +4,86 @@
 Distributing collections
 ************************
 
-You can distribute your collections by publishing them on a distribution server. Distribution servers include Ansible Galaxy, Red Hat Automation Hub, and privately hosted Automation Hub instances. You can publish any collection to Ansible Galaxy and/or to a privately hosted Automation Hub instance. If your collection is certified by Red Hat, you can publish it to the Red Hat Automation Hub.
+A collection is a distribution format for Ansible content. A typical collection contains modules and other plugins that address a set of related use cases. For example, a collection might automate administering a particular database. A collection can also contain roles and playbooks.
 
-Distributing collections involves three major steps:
-#. Configuring your distribution server(s)
-#. Building your collection artifact
+To distribute your collection and allow others to use it, you can publish your collection on one or more distribution servers. Distribution servers include:
+
+================================= ========================================================
+Distribution server               Collections accepted
+================================= ========================================================
+Ansible Galaxy                    All collections
+Red Hat Automation Hub            Only collections certified by Red Hat
+Privately hosted Automation Hub   Collections authorized by the owners
+================================= ========================================================
+
+Distributing collections involves four major steps:
+
+#. Initial configuration of your distribution server or servers
+#. Building your collection tarball
+#. Preparing to publish your collection
 #. Publishing your collection
 
 .. contents::
    :local:
    :depth: 2
 
-Configuring your distribution server or servers
-================================================
+.. _config_distribution_server:
+
+Initial configuration of your distribution server or servers
+============================================================
 
-1. Get a namespace on each distribution server you want to use (Galaxy, private Automation Hub, Red Hat Automation Hub).
+Configure a connection to one or more distribution servers so you can publish collections there. You only need to configure each distribution server once. You must repeat the other steps (building your collection tarball, preparing to publish, and publishing your collection) every time you publish a new collection or a new version of an existing collection.
+
+1. Create a namespace on each distribution server you want to use.
 2. Get an API token for each distribution server you want to use.
 3. Specify the API token for each distribution server you want to use.
 
-Getting a namespace
--------------------
+.. _get_namespace:
+
+Creating a namespace
+--------------------
+
+You must upload your collection into a namespace on each distribution server. If you have a login for Ansible Galaxy, your Ansible Galaxy username is usually also an Ansible Galaxy namespace.
 
-You need a namespace on Galaxy and/or Automation Hub to upload your collection. To get a namespace:
+.. warning::
 
-* For Galaxy, see `Galaxy namespaces <https://galaxy.ansible.com/docs/contributing/namespaces.html#galaxy-namespaces>`_ on the Galaxy docsite for details.
-* For Automation Hub, see the `Ansible Certified Content FAQ <https://access.redhat.com/articles/4916901>`_.
+   Namespaces on Ansible Galaxy cannot include hyphens. If you have a login for Ansible Galaxy that includes a hyphen, your Galaxy username is not also a Galaxy namespace. For example, ``awesome-user`` is a valid username for Ansible Galaxy, but it is not a valid namespace.
+
+You can create additional namespaces on Ansible Galaxy if you choose. For Red Hat Automation Hub and private Automation Hub you must create a namespace before you can upload your collection. To create a namespace:
+
+* To create a namespace on Galaxy, see `Galaxy namespaces <https://galaxy.ansible.com/docs/contributing/namespaces.html#galaxy-namespaces>`_ on the Galaxy docsite for details.
+* To create a namespace on Red Hat Automation Hub, see the `Ansible Certified Content FAQ <https://access.redhat.com/articles/4916901>`_.
+
+Specify the namespace in the :file:`galaxy.yaml` file for each collection. For more information on the :file:`galaxy.yaml` file, see :ref:`collections_galaxy_meta`.
 
 .. _galaxy_get_token:
 
 Getting your API token
 ----------------------
 
-You need an API token for Galaxy and/or Automation Hub to upload your collection. Use the API token(s) to authenticate your connection to the distribution server(s) and protect your content.
+An API token authenticates your connection to each distribution server. You need a separate API token for each distribution server. Use the correct API token to connect to each distribution server securely and protect your content.
 
 To get your API token:
 
-* For Galaxy, go to the `Galaxy profile preferences <https://galaxy.ansible.com/me/preferences>`_ page and click :guilabel:`API Key`.
-* For Automation Hub, go to `the token page <https://cloud.redhat.com/ansible/automation-hub/token/>`_ and click :guilabel:`Load token`.
+* To get an API token for Galaxy, go to the `Galaxy profile preferences <https://galaxy.ansible.com/me/preferences>`_ page and click :guilabel:`API Key`.
+* To get an API token for Automation Hub, go to `the token page <https://cloud.redhat.com/ansible/automation-hub/token/>`_ and click :guilabel:`Load token`.
 
-Specifying your API token
--------------------------
-
-Once you have retrieved your API token, you can specify the correct token for each distribution server in two ways:
+.. _galaxy_specify_token:
 
-* Pass the token to  the ``ansible-galaxy`` command using the ``--token``.
-* Configure the token within a Galaxy server list in your :file:`ansible.cfg` file.
+Specifying your API token and distribution server
+-------------------------------------------------
 
-Specifying your API token with the ``--token`` argument
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Each time you publish a collection, you must specify the API token and the distribution server to create a secure connection. You have two options for specifying the token and distribution server:
 
-You can use the ``--token`` argument with the ``ansible-galaxy`` command (in conjunction with the ``--server`` argument or :ref:`GALAXY_SERVER` setting in your :file:`ansible.cfg` file). You cannot use ``apt-key`` with any servers defined in your :ref:`Galaxy server list <galaxy_server_config>`.
+* You can configure the token in configuration, as part of a ``galaxy_server_list`` entry in your :file:`ansible.cfg` file. Using configuration is the most secure option.
+* You can pass the token at the command line as an argument to the ``ansible-galaxy`` command. If you pass the token at the command line, you can specify the server at the command line, by using the default setting, or by setting the server in configuration. Passing the token at the command line is insecure, because typing secrets at the command line may expose them to other users on the system.
 
-.. code-block:: text
+.. _galaxy_token_ansible_cfg:
 
-    ansible-galaxy collection publish ./geerlingguy-collection-1.2.3.tar.gz --token=<key goes here>
-
-Specifying your API token with a Galaxy server list
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-You can configure one or more distribution servers for Galaxy in your :file:`ansible.cfg` file under the ``galaxy_server_list`` section. For each server, you also configure the token.
+Specifying the token and distribution server in configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+By default, Ansible Galaxy is configured as the only distribution server. You can add other distribution servers and specify your API token or tokens in configuration by editing the ``galaxy_server_list`` section of your :file:`ansible.cfg` file. This is the most secure way to manage authentication for distribution servers. Specify a URL and token for each server. For example:
 
 .. code-block:: ini
 
@@ -72,22 +92,46 @@ You can configure one or more distribution servers for Galaxy in your :file:`ans
 
    [galaxy_server.release_galaxy]
    url=https://galaxy.ansible.com/
-   token=my_token
+   token=abcdefghijklmnopqrtuvwxyz
+
+You cannot use ``apt-key`` with any servers defined in your :ref:`galaxy_server_list <galaxy_server_config>`. See :ref:`galaxy_server_config` for complete details.
+
+.. _galaxy_use_token_arg:
+
+Specifying the token at the command line
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can specify the API token at the command line using the ``--token`` argument of the :ref:`ansible-galaxy` command. There are three ways to specify the distribution server when passing the token at the command line:
+
+* using the ``--server`` argument of the :ref:`ansible-galaxy` command
+* relying on the default (https://galaxy.ansible.com)
+* setting a server in configuration by creating a :ref:`GALAXY_SERVER` setting in your :file:`ansible.cfg` file
+
+For example:
+
+.. code-block:: bash
+
+     ansible-galaxy collection publish path/to/my_namespace-my_collection-1.0.0.tar.gz --token abcdefghijklmnopqrtuvwxyz
+
+.. warning::
 
-See :ref:`galaxy_server_config` for complete details.
+   Using the ``--token`` argument is insecure. Passing secrets at the command line may expose them to others on the system.
 
 .. _building_collections:
 
-Building a collection tarball
-=============================
+Building your collection tarball
+================================
 
-Once you have configured one or more distribution servers, you must build a collection tarball. To build a collection, run ``ansible-galaxy collection build`` from inside the root directory of the collection:
+After configuring one or more distribution servers, build a collection tarball. The collection tarball is the published artifact, the object that you upload and other users download to install your collection. To build a collection tarball:
+
+#. Review the version number in your :file:`galaxy.yaml` file. Each time you publish your collection, it must have a new version number. You cannot make changes to existing versions of your collection on a distribution server. If you try to upload the same collection version more than once, the distribution server returns the error ``Code: conflict.collection_exists``. Collections follow semantic versioning rules. For more information on versions, see :ref:`collection_versions`. For more information on the :file:`galaxy.yaml` file, see :ref:`collections_galaxy_meta`.
+#. Run ``ansible-galaxy collection build`` from inside the top-level directory of the collection. For example:
 
 .. code-block:: bash
 
     collection_dir#> ansible-galaxy collection build
 
-This creates a tarball of the built collection in the current directory which can be uploaded to your distribution server::
+This command builds a tarball of the collection in the current directory, which you can upload to your selected distribution server::
 
     my_collection/
     ├── galaxy.yml
@@ -96,37 +140,33 @@ This creates a tarball of the built collection in the current directory which ca
     └── ...
 
 .. note::
-   * Certain files and folders are excluded when building the collection artifact. See :ref:`ignoring_files_and_folders_collections`  to exclude other files you would not want to distribute.
-   * If you used the now-deprecated ``Mazer`` tool for any of your collections, delete any and all files it added to your :file:`releases/` directory before you build your collection with ``ansible-galaxy``.
+   * To reduce the size of collections, certain files and folders are excluded from the collection tarball by default. See :ref:`ignoring_files_and_folders_collections` if your collection directory contains other files you want to exclude.
    * The current Galaxy maximum tarball size is 2 MB.
 
-This tarball is mainly intended to upload to Galaxy as a distribution method, but you can use it directly to install the collection on target systems.
+You can upload your tarball to one or more distribution servers. You can also distribute your collection locally by copying the tarball to install your collection directly on target systems.
 
 .. _ignoring_files_and_folders_collections:
 
 Ignoring files and folders
 --------------------------
 
-By default the build step will include all the files in the collection directory in the final build artifact except for the following:
+By default the build step includes all the files in the collection directory in the tarball except for the following:
 
 * ``galaxy.yml``
 * ``*.pyc``
 * ``*.retry``
 * ``tests/output``
-* previously built artifacts in the root directory
-* various version control directories like ``.git/``
+* previously built tarballs in the root directory
+* various version control directories such as ``.git/``
 
-To exclude other files and folders when building the collection, you can set a list of file glob-like patterns in the
-``build_ignore`` key in the collection's ``galaxy.yml`` file. These patterns use the following special characters for
-wildcard matching:
+To exclude other files and folders from your collection tarball, set a list of file glob-like patterns in the ``build_ignore`` key in the collection's ``galaxy.yml`` file. These patterns use the following special characters for wildcard matching:
 
 * ``*``: Matches everything
 * ``?``: Matches any single character
-* ``[seq]``: Matches and character in seq
-* ``[!seq]``:Matches any character not in seq
+* ``[seq]``: Matches any character in sequence
+* ``[!seq]``:Matches any character not in sequence
 
-For example, if you wanted to exclude the :file:`sensitive` folder within the ``playbooks`` folder as well any ``.tar.gz`` archives you
-can set the following in your ``galaxy.yml`` file:
+For example, to exclude the :file:`sensitive` folder within the ``playbooks`` folder as well any ``.tar.gz`` archives, set the following in your ``galaxy.yml`` file:
 
 .. code-block:: yaml
 
@@ -134,77 +174,95 @@ can set the following in your ``galaxy.yml`` file:
      - playbooks/sensitive
      - '*.tar.gz'
 
+For more information on the :file:`galaxy.yml` file, see :ref:`collections_galaxy_meta`.
+
 .. note::
-     This feature is only supported when running ``ansible-galaxy collection build`` with Ansible 2.10 or newer.
+     The ``build_ignore`` feature is only supported with ``ansible-galaxy collection build`` in Ansible 2.10 or newer.
 
-.. _collection_versions:
+.. _trying_collection_locally:
 
-Collection versions
-===================
+Preparing to publish your collection
+====================================
 
-Each time you publish your collection, you create a new version. Once you publish a version of a collection, you cannot delete or modify that version. Ensure that everything looks okay before publishing. The only way to change a collection is to release a new version. The latest version of a collection (by highest version number) will be the version displayed everywhere in Galaxy or Automation Hub; however, users will still be able to download older versions.
+Each time you publish your collection, you must create a :ref:`new version <collection_versions>` on the distribution server. After you publish a version of a collection, you cannot delete or modify that version. To avoid unnecessary extra versions, check your collection for bugs, typos, and other issues locally before publishing:
 
-Collection versions use `Semantic Versioning <https://semver.org/>`_ for version numbers. Please read the official documentation for details and examples. In summary:
+#. Install the collection locally.
+#. Review the locally installed collection before publishing a new version.
 
-* Increment major (for example: x in `x.y.z`) version number for an incompatible API change.
-* Increment minor (for example: y in `x.y.z`) version number for new functionality in a backwards compatible manner (for example new modules/plugins, parameters, return values).
-* Increment patch (for example: z in `x.y.z`) version number for backwards compatible bug fixes.
+Installing your collection locally
+----------------------------------
 
+You have two options for installing your collection locally:
 
-.. _trying_collection_locally:
+  * Install your collection locally from the tarball.
+  * Install your collection locally from your git repository.
 
-Trying collections locally
-==========================
+Installing your collection locally from the tarball
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To install your collection locally from the tarball, run ``ansible-galaxy collection install`` and specify the collection tarball. You can optionally specify a location using the ``-p`` flag. For example:
+
+.. code-block:: bash
+
+   collection_dir#> ansible-galaxy collection install my_namespace-my_collection-1.0.0.tar.gz -p ./collections
+
+Install the tarball into a directory configured in :ref:`COLLECTIONS_PATHS` so Ansible can easily find and load the collection. If you do not specify a path value, ``ansible-galaxy collection install`` installs the collection in the first path defined in :ref:`COLLECTIONS_PATHS`.
 
-Before you publish your collection, test it out locally. Every time you publish a tarball, you create a :ref:`new version <collection_versions>` of your collection. Testing the collection locally gives you confidence that the new version will contain the functionality you want without unexpected behavior.
+.. _collections_scm_install:
 
-Trying your collection from the tarball
----------------------------------------
+Installing your collection locally from a git repository
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-You can try your collection locally by installing it from the tarball. The following will enable an adjacent playbook to access the collection:
+To install your collection locally from a git repository, specify the repository and the branch you want to install:
 
 .. code-block:: bash
 
-   ansible-galaxy collection install my_namespace-my_collection-1.0.0.tar.gz -p ./collections
+   collection_dir#> ansible-galaxy collection install git+https://github.com/org/repo.git,devel
 
+.. include:: ../shared_snippets/installing_collections_git_repo.txt
 
-You should use one of the values configured in :ref:`COLLECTIONS_PATHS` for your path. This is also where Ansible itself will
-expect to find collections when attempting to use them. If you don't specify a path value, ``ansible-galaxy collection install``
-installs the collection in the first path defined in :ref:`COLLECTIONS_PATHS`, which by default is ``~/.ansible/collections``.
+Reviewing your collection
+-------------------------
 
-If you want to use a collection directly out of a checked out git repository, see :ref:`hacking_collections`.
+Review the collection:
 
-Next, try using the local collection inside a playbook. For examples and more details see :ref:`Using collections <using_collections>`
+* Run a playbook that uses the modules and plugins in your collection. Verify that new features and functionality work as expected. For examples and more details see :ref:`Using collections <using_collections>`.
+* Check the documentation for typos.
+* Check that the version number of your tarball is higher than the latest published version on the distribution server or servers.
+* If you find any issues, fix them and rebuild the collection tarball.
 
-.. _collections_scm_install:
+.. _collection_versions:
 
-Trying your collection from a git repository
---------------------------------------------
+Understanding collection versioning
+-----------------------------------
 
-You can also test a version of your collection in development by installing it from a git repository.
+The only way to change a collection is to release a new version. The latest version of a collection (by highest version number) is the version displayed everywhere in Galaxy and Automation Hub. Users can still download older versions.
 
-.. code-block:: bash
+Follow semantic versioning when setting the version for your collection. In summary:
 
-   ansible-galaxy collection install git+https://github.com/org/repo.git,devel
+* Increment the major version number, ``x`` of ``x.y.z``, for an incompatible API change.
+* Increment the minor version number, ``y`` of ``x.y.z``, for new functionality in a backwards compatible manner (for example new modules/plugins, parameters, return values).
+* Increment the patch version number, ``z`` of ``x.y.z``, for backwards compatible bug fixes.
 
-.. include:: ../shared_snippets/installing_collections_git_repo.txt
+Read the official `Semantic Versioning <https://semver.org/>`_ documentation for details and examples.
+
+.. _publish_collection:
 
-Publishing a collection
-=======================
+Publishing your collection
+==========================
 
-Once you have a namespace and an API token for each distribution server you want to use, and you have created and tested a collection tarball, you can distribute your collection by publishing the tarball to Ansible Galaxy, Red Hat Automation Hub, or a privately hosted Automation Hub instance. You can use either the ``ansible-galaxy collection publish`` command or the distribution server (Galaxy, Automation Hub) itself.
+The last step in distributing your collection is publishing the tarball to Ansible Galaxy, Red Hat Automation Hub, or a privately hosted Automation Hub instance. You can publish your collection in two ways:
 
-Each time you add features or make changes to your collection, you must create a new collection artifact and publish a new version of the collection. For details on versioning, see :ref:`collection_versions`.
+* from the command line using the ``ansible-galaxy collection publish`` command
+* from the website of the distribution server (Galaxy, Automation Hub) itself
 
 .. _upload_collection_ansible_galaxy:
+.. _publish_collection_galaxy_cmd:
 
-Publish a collection using ``ansible-galaxy``
+Publishing a collection from the command line
 ---------------------------------------------
 
-.. note::
-  By default, ``ansible-galaxy`` uses https://galaxy.ansible.com as the Galaxy server (as listed in the :file:`ansible.cfg` file under :ref:`galaxy_server`). If you are only publishing your collection to Ansible Galaxy, you do not need any further configuration. If you are using Red Hat Automation Hub or any other Galaxy server, see :ref:`Configuring the ansible-galaxy client <galaxy_server_config>`.
-
-To upload the collection artifact with the ``ansible-galaxy`` command:
+To upload the collection tarball from the command line using ``ansible-galaxy``:
 
 .. code-block:: bash
 
@@ -212,29 +270,30 @@ To upload the collection artifact with the ``ansible-galaxy`` command:
 
 .. note::
 
-	The above command assumes you have retrieved and stored your API token as part of a Galaxy server list. See :ref:`galaxy_get_token` for details.
+	This ansible-galaxy command assumes you have retrieved and stored your API token in configuration. See :ref:`galaxy_specify_token` for details.
 
 The ``ansible-galaxy collection publish`` command triggers an import process, just as if you uploaded the collection through the Galaxy website. The command waits until the import process completes before reporting the status back. If you want to continue without waiting for the import result, use the ``--no-wait`` argument and manually look at the import progress in your `My Imports <https://galaxy.ansible.com/my-imports/>`_ page.
 
-
 .. _upload_collection_galaxy:
 
-Publishing a collection using the Galaxy website
-------------------------------------------------
+Publishing a collection from the website
+----------------------------------------
 
 To publish your collection directly on the Galaxy website:
 
 #. Go to the `My Content <https://galaxy.ansible.com/my-content/namespaces>`_ page, and click the **Add Content** button on one of your namespaces.
 #. From the **Add Content** dialogue, click **Upload New Collection**, and select the collection archive file from your local filesystem.
 
-When you upload a collection, it always uploads to the namespace specified in the collection metadata in the ``galaxy.yml`` file, no matter which namespace you select on the website. If you are not an owner of the namespace specified in your collection metadata, the upload request will fail.
+When you upload a collection, Ansible always uploads the tarball to the namespace specified in the collection metadata in the ``galaxy.yml`` file, no matter which namespace you select on the website. If you are not an owner of the namespace specified in your collection metadata, the upload request fails.
 
-Once Galaxy uploads and accepts a collection, you will be redirected to the **My Imports** page, which displays output from the import process, including any errors or warnings about the metadata and content contained in the collection.
+After Galaxy uploads and accepts a collection, the website shows you the **My Imports** page. This page shows import process information. You can review any errors or warnings about your upload there.
 
 .. seealso::
 
    :ref:`collections`
        Learn how to install and use collections.
+   :ref:`collections_galaxy_meta`
+       Table of fields used in the :file:`galaxy.yml` file
    `Mailing List <https://groups.google.com/group/ansible-devel>`_
        The development mailing list
    `irc.libera.chat <https://libera.chat/>`_
diff --git a/docs/docsite/rst/dev_guide/developing_collections_shared.rst b/docs/docsite/rst/dev_guide/developing_collections_shared.rst
index 8e43695e04..33b1e71e7f 100644
--- a/docs/docsite/rst/dev_guide/developing_collections_shared.rst
+++ b/docs/docsite/rst/dev_guide/developing_collections_shared.rst
@@ -4,7 +4,7 @@
 Using shared resources in collections
 *************************************
 
-Although developing Ansible modules contained in collections is similar to developing standalone Ansible modules, you use shared resources like documentation fragments and module utilities differently in collections. You can use documentation fragments within and across collections. You can use optional module utilities to support multiple versions of ansible-core in your collection.
+Although developing Ansible modules contained in collections is similar to developing standalone Ansible modules, you use shared resources like documentation fragments and module utilities differently in collections. You can use documentation fragments within and across collections. You can use optional module utilities to support multiple versions of ansible-core in your collection. Collections can also depend on other collections.
 
 .. contents::
    :local:
@@ -65,6 +65,23 @@ By wrapping the import statement in a ``try`` block, the payload builder will om
 
 The optional import behavior also applies to module_utils imported from collections.
 
+.. _collection_dependencies:
+
+Listing collection dependencies
+===============================
+
+We recommend that collections work as standalone, independent units, depending only on ansible-core. However, if your collection must depend on features and functionality from another collection, list the other collection or collections under ``dependencies`` in your collection's :file:`galaxy.yml` file. For more information on the :file:`galaxy.yml` file, see :ref:`collections_galaxy_meta`.
+
+You can use git repositories for collection dependencies during local development and testing. For example:
+
+.. code-block:: yaml
+
+   dependencies: {'git@github.com:organization/repo_name.git': 'devel'}
+
+.. warning
+
+   Do not use git repositories as dependencies for published collections. Dependencies for published collections must be other published collections.
+
 .. seealso::
 
    :ref:`collections`
diff --git a/docs/docsite/rst/shared_snippets/installing_collections_git_repo.txt b/docs/docsite/rst/shared_snippets/installing_collections_git_repo.txt
index b6b0384a71..d804b5dd22 100644
--- a/docs/docsite/rst/shared_snippets/installing_collections_git_repo.txt
+++ b/docs/docsite/rst/shared_snippets/installing_collections_git_repo.txt
@@ -1,8 +1,13 @@
-You can install a collection in a git repository by providing the URI to the repository instead of a collection name or path to a ``tar.gz`` file. The collection must contain a ``galaxy.yml`` or ``MANIFEST.json`` file, which will be used to generate the would-be collection artifact data from the directory. The URI should be prefixed with ``git+`` (or with ``git@`` to use a private repository with ssh authentication) and optionally supports a comma-separated `git commit-ish <https://git-scm.com/docs/gitglossary#def_commit-ish>`_ version (for example, a commit or tag).
+You can install a collection from a git repository instead of from Galaxy or Automation Hub. As a developer, installing from a git repository lets you review your collection before you create the tarball and publish the collection. As a user, installing from a git repository lets you use collections or versions that are not in Galaxy or Automation Hub yet.
 
-.. warning::
+The repository must contain a ``galaxy.yml`` or ``MANIFEST.json`` file. This file provides metadata such as the version number and namespace of the collection.
+
+Installing a collection from a git repository at the command line
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To install a collection from a git repository at the command line, use the URI of the repository instead of a collection name or path to a ``tar.gz`` file.  Prefix the URI with ``git+`` (or with ``git@`` to use a private repository with ssh authentication). You can specify a branch, commit, or tag using the comma-separated `git commit-ish <https://git-scm.com/docs/gitglossary#def_commit-ish>`_ syntax.
 
-   Embedding credentials into a git URI is not secure. Make sure to use safe auth options for security reasons. For example, use `SSH <https://help.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh>`_, `netrc <https://linux.die.net/man/5/netrc>`_ or `http.extraHeader <https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpextraHeader>`_/`url.<base>.pushInsteadOf <https://git-scm.com/docs/git-config#Documentation/git-config.txt-urlltbasegtpushInsteadOf>`_ in Git config to prevent your creds from being exposed in logs.
+For example:
 
 .. code-block:: bash
 
@@ -13,29 +18,26 @@ You can install a collection in a git repository by providing the URI to the rep
    ansible-galaxy collection install git@github.com:organization/repo_name.git
 
    # Install a collection from a local git repository
-   ansible-galaxy collection install git+file:///home/user/path/to/repo/.git
-
-In a ``requirements.yml`` file, you can also use the ``type`` and ``version`` keys in addition to using the ``git+repo,version`` syntax for the collection name.
-
-.. code-block:: yaml
-
-   collections:
-     - name: https://github.com/organization/repo_name.git
-       type: git
-       version: devel
+   ansible-galaxy collection install git+file:///home/user/path/to/repo_name.git
 
-Git repositories can be used for collection dependencies as well. This can be helpful for local development and testing but built/published artifacts should only have dependencies on other artifacts.
+.. warning::
 
-.. code-block:: yaml
+   Embedding credentials into a git URI is not secure. Use safe authentication options to prevent your credentials from being exposed in logs or elsewhere. 
+   
+   * Use `SSH <https://help.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh>`_ authentication
+   * Use `netrc <https://linux.die.net/man/5/netrc>`_ authentication
+   * Use `http.extraHeader <https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpextraHeader>`_ in your git configuration
+   * Use `url.<base>.pushInsteadOf <https://git-scm.com/docs/git-config#Documentation/git-config.txt-urlltbasegtpushInsteadOf>`_ in your git configuration
 
-   dependencies: {'git@github.com:organization/repo_name.git': 'devel'}
+Specifying the collection location within the git repository
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Default repository search locations
------------------------------------
+When you install a collection from a git repository, Ansible uses the collection ``galaxy.yml`` or ``MANIFEST.json`` metadata file to build the collection. By default, Ansible searches two paths for collection ``galaxy.yml`` or ``MANIFEST.json`` metadata files:
 
-There are two paths searched in a repository for collections by default.
+* The top level of the repository.
+* Each directory in the repository path (one level deep).
 
-The first is the ``galaxy.yml`` or ``MANIFEST.json`` file in the top level of the repository path. If the file exists it's used as the collection metadata and the individual collection will be installed.
+If a ``galaxy.yml`` or ``MANIFEST.json`` file exists in the top level of the repository, Ansible uses the collection metadata in that file to install an individual collection.
 
 .. code-block:: text
 
@@ -46,39 +48,58 @@ The first is the ``galaxy.yml`` or ``MANIFEST.json`` file in the top level of th
    │   └── module_utils/
    └─── README.md
 
-The second is a ``galaxy.yml`` or ``MANIFEST.json`` file in each directory in the repository path (one level deep). In this scenario, each directory with a metadata file is installed as a collection.
+If a ``galaxy.yml`` or ``MANIFEST.json`` file exists in one or more directories in the repository path (one level deep), Ansible installs each directory with a metadata file as a collection. For example, Ansible installs both collection1 and collection2 from this repository structure by default:
 
 .. code-block:: text
 
-   directory/
-   ├── docs/
-   ├── MANIFEST.json
-   ├── plugins/
-   │   ├── inventory/
-   │   └── modules/
-   └── roles/
+   ├── collection1
+   │   ├── docs/
+   │   ├── galaxy.yml
+   │   └── plugins/
+   │       ├── inventory/
+   │       └── modules/
+   └── collection2
+       ├── docs/
+       ├── galaxy.yml
+       ├── plugins/
+       |   ├── filter/
+       |   └── modules/
+       └── roles/
+
+If you have a different repository structure or only want to install a subset of collections, you can add a fragment to the end of your URI (before the optional comma-separated version) to indicate the location of the metadata file or files. The path should be a directory, not the metadata file itself. For example, to install only collection2 from the example repository with two collections:
 
-Specifying the location to search for collections
--------------------------------------------------
+.. code-block:: text
 
-If you have a different repository structure or only want to install a subset of collections, you can add a fragment to the end of your URI (before the optional comma-separated version) to indicate which path ansible-galaxy should inspect for metadata file(s). The path should be a directory to a collection or multiple collections (rather than the path to a ``galaxy.yml`` file or ``MANIFEST.json`` file).
+   ansible-galaxy collection install git+https://github.com/organization/repo_name.git#/collection2/
+
+In some repositories, the main directory corresponds to the namespace:
 
 .. code-block:: text
 
    namespace/
-   └── name/
+   ├── collectionA/
+   |   ├── docs/
+   |   ├── galaxy.yml
+   |   ├── plugins/
+   |   │   ├── README.md
+   |   │   └── modules/
+   |   ├── README.md
+   |   └── roles/
+   └── collectionB/
        ├── docs/
        ├── galaxy.yml
        ├── plugins/
-       │   ├── README.md
+       │   ├── connection/
        │   └── modules/
        ├── README.md
        └── roles/
 
+You can install all collections in this repository, or install one collection from a specific commit:
+
 .. code-block:: bash
 
-   # Install all collections in a particular namespace
+   # Install all collections in the namespace
    ansible-galaxy collection install git+https://github.com/organization/repo_name.git#/namespace/
 
    # Install an individual collection using a specific commit
-   ansible-galaxy collection install git+https://github.com/organization/repo_name.git#/namespace/name/,7b60ddc245bc416b72d8ea6ed7b799885110f5e5
+   ansible-galaxy collection install git+https://github.com/organization/repo_name.git#/namespace/collectionA/,7b60ddc245bc416b72d8ea6ed7b799885110f5e5
diff --git a/docs/docsite/rst/shared_snippets/installing_multiple_collections.txt b/docs/docsite/rst/shared_snippets/installing_multiple_collections.txt
index e8c40b2343..a1bf0265f6 100644
--- a/docs/docsite/rst/shared_snippets/installing_multiple_collections.txt
+++ b/docs/docsite/rst/shared_snippets/installing_multiple_collections.txt
@@ -1,5 +1,5 @@
 
-You can also setup a ``requirements.yml`` file to install multiple collections in one command. This file is a YAML file in the format:
+You can set up a ``requirements.yml`` file to install multiple collections in one command. This file is a YAML file in the format:
 
 .. code-block:: yaml+jinja
 
@@ -13,14 +13,27 @@ You can also setup a ``requirements.yml`` file to install multiple collections i
      version: 'version range identifiers (default: ``*``)'
      source: 'The Galaxy URL to pull the collection from (default: ``--api-server`` from cmdline)'
 
-The supported keys for collection requirement entries are ``name``, ``version``, ``source``, and ``type``.
+You can specify four keys for each collection entry:
 
-The ``version`` key can take in the same range identifier format documented above. If you're installing a collection from a git repository instead of a built collection artifact, the ``version`` key refers to a `git commit-ish <https://git-scm.com/docs/gitglossary#def_commit-ish>`_.
+  * ``name``
+  * ``version``
+  * ``source``
+  * ``type``
+
+The ``version`` key uses the same range identifier format documented in :ref:`collections_older_version`. 
 
 The ``type`` key can be set to ``galaxy``, ``url``, ``file``, and ``git``. If ``type`` is omitted, the ``name`` key is used to implicitly determine the source of the collection.
 
-Roles can also be specified and placed under the ``roles`` key. The values follow the same format as a requirements
-file used in older Ansible releases.
+When you install a collection with ``type: git``, the ``version`` key can refer to a branch or to a `git commit-ish <https://git-scm.com/docs/gitglossary#def_commit-ish>`_ object (commit or tag). For example:
+
+.. code-block:: yaml
+
+   collections:
+     - name: https://github.com/organization/repo_name.git
+       type: git
+       version: devel
+
+You can also add roles to a ``requirements.yml`` file, under the ``roles`` key. The values follow the same format as a requirements file used in older Ansible releases.
 
 .. code-block:: yaml
 
@@ -42,10 +55,7 @@ To install both roles and collections at the same time with one command, run the
 
     $ ansible-galaxy install -r requirements.yml
 
-Running ``ansible-galaxy collection install -r`` or ``ansible-galaxy role install -r`` will only install collections,
-or roles respectively.
+Running ``ansible-galaxy collection install -r`` or ``ansible-galaxy role install -r`` will only install collections, or roles respectively.
 
 .. note::
-    Installing both roles and collections from the same requirements file will not work when specifying a custom
-    collection or role install path. In this scenario the collections will be skipped and the command will process
-    each like ``ansible-galaxy role install`` would.
+    Installing both roles and collections from the same requirements file will not work when specifying a custom collection or role install path. In this scenario the collections will be skipped and the command will process each like ``ansible-galaxy role install`` would.