Documentation Feedback / Suggestions

[orthanc]

The below are notes / questions that I had as a newbie to the collections functionality after
on my first reading of https://github.com/bcoca/collection/blob/master/collections.rst

Current state is almost certainly fine for the initial tech preview, but I'm hoping these help
with identifying the additional information that would be useful before this functionality goes GA.

Docs would benefit from a why / when section

With the current docs there doesn't seem to be good guidance on why I would create a collection / when I would use one (as opposed to other sharing mechanisms).

E.g.

• I'm not sure when a collection is preferable to traditional galaxy roles for distributing roles. Is it only if there are plugins to distribute as well or is there some intrinsic benefit
• What circumstances make sense to distribute a fully-formed playbook (and associated inventory) rather than roles?

I'm making assumptions about the purpose of collections so it's entirely possible that the rest of the comments are irrelevant if my assumptions are way off.

Embedded Playbooks and inventory

There's a TODO for playbooks so perhaps this is intended to be covered there (or would be clarified by the why / when section) but the intended use of inventory and playbooks, what is good and what is dangerous is not clear to me.

• How do you invoke a playbook embedded in a collection?
• What use is an embedded inventory? Wouldn't inventory always be specific to the environment you're running the playbook for?
• How does embedded inventory interact with general inventory? Is it additive & merged or do you always use one or the other.

Things I assume you can / can't do but would be good to be explicit

Below is a list of things that reading the doc I assumed are / aren't possible but was not 100% clear so if these are possible / are not intended might benefit from some examples or explicit docs.

• I assume roles / playbooks in a collection can use plugins from collections pulled in as dependencies
• I'm not sure whether plugins in a collection can use module_utils from a collection pulled in as a dependency
  • even if it works, I'm not sue that it's a good idea
• I assume collections / collection roles can't depend on traditional roles from galaxy using requirements.yml or similar
• I assume that a role or playbook in a collection does not need to add the namespace to use modules or plugins from the same collection
• I assume there is no way to use the namespace keyword in a role, only in a playbook.

Namespace selection

In the galaxy.yml section it talks about the constraints on namespaces (valid python identifier etc) but doesn't tie it back to the use / ownership of galaxy namespaces. Further on in the uploading collections section it does explain that you must own the namespace on galaxy.

It would be much clearer to me if the link to the galaxy site was made explicit in galaxy.yml section.

Use of FQCN Acronym

I find the use of FQCN for fully qualified collection name makes it harder to read the doc. It is defined in the doc but skipping around sections I have to keep reminding myself what it means. It think it would be easier to read if we just skipped the acronym and just used fully qualified collection name instead.

Particularly the first use of FQCN is before the definition.