Documentation Overhaul - The Examples are Useless in Most Cases and Descriptions are Lacking in Definition

[rgadwagner]

SUMMARY

There are several issues with the general documentation of the VMWARE REST collection. Specifically the examples are useless outside of a specific workflow and many of the descriptions of fields use their own field name to define what the field is. For instance "id: identifier of..." (No one needs to know that "ID" means "Identifier", they DO need to know what TYPE of identifier the code is looking for and how to get it which is not documented.)

Regarding the examples on most of the Collection, the examples create a thing, use the ID from the created thing to do the next task, which uses the output of that task to do the next, etc. till complete. While this works in a testing environment this is completely useless in any environment where someone is not following this process step by step and it answers NO questions about what or how to use the rest API in any way that isn't part of the example.

VCENTER_OVF_LIBRARYITEM: For Instance (one of Many): In vcenter_ovf_libraryitem the examples at the bottom begin by creating a VM (which has nothing to do with VMWare OVF Library Item's code), then creating an OVF Library (again, nothing to do with using vcenter_ovf_libraryitem) and then exporting the Created VM above to the newly created OVF Library Item.

However, the important steps use data from prior execution: For instance, the "Export the VM as an OVF on the library" includes "id: '{{ my_vm.id }}'" which comes from the first example (registered output from the vm creation) and "library_id: '{{ nfs_lib.id }}'" which comes from the second example (creation of the OVF Library itself - more registered output). There is no indication of what either "my_vm.id" is or what "nfs_lib.id" is. Worse, you can RUN these examples and STILL not know what these IDs are or how they're used...the use of registered variables from prior example steps that have nothing to do with the execution of the module you're documenting is exceptionally poor practice.

Are these IDs MOIDs? Names? UUIDs? The documentation describes these ids as: "id (str): Identifier of the deployable resource. ([‘present’])" - So an ID is an Identifier...that's...not helpful...especially since VMWare contains at least 3 different "identifiers" for any given object (it's Name, it's MOID and it's UUID). Given that half the collection is lookup code, I would have expected the examples to AT LEAST use rest lookups to OBTAIN the ID information for the VM and Library instead of burring the IDs definitions in registered variables that are neither printed nor documented anywhere within the example code.

Yes, users can take your examples, create a playbook, and run each step with debugs to show the output to understand what's going on, but this isn't an 'example' this is a "do it yourself exercise" which isn't documentation...it's class homework. Ansible documentation is supposed to identify what and how the module is used and the examples are supposed to show common use cases of how the module does the various things that the module supports doing. These examples do none of this.

Again, running these examples provides NO useful information since all of the questions are obscured by the use of registered variables from prior documentation that doesn't apply to the use of this module. They ONLY work if this is your EXACT process. If your process isn't creating a vmware content library (which would only happen once) then you have no guidance, either through the definition of the attributes or through the examples of what the module is requiring for each field.

Further, as noted before, the examples cover only a small subset of functionality in the module...in the case of vmware_ovf_libraryitem, it covers ONLY uploading an OVF to a new OVF Content Library Container Object, there is absolutely no guidance on how to upload an existing VM to an existing library and/or into an existing content item. For this SPECIFIC module, this is further obscured by the fact that attribute definition information is just plain wrong:

target 
   Specification of the target content library and library item. This parameter is mandatory.  Valid attributes are:
        library_id (str): Identifier of the library in which a new library item should be created. This field is not used if the #library_item_id field is specified. 
        library_item_id (str): Identifier of the library item that should be should be updated. ([‘present’])

This information is, at best, misleading. Library_ID is still a REQUIRED FIELD when passing in Library_Item_ID, even though your documentation states it is unused (which is not expected behavior). While the documentation does not EXPLICITLY say "do not pass library_id when passing library_item_id" it also does not explicitly say "pass both library_id and library_item_id, but library_id is unused". The reader is left to question how to upload an OVF to an existing Library and an existing Library ID...and there is no example in the examples section that comes close to dealing with this possibility.

These examples might as well say "Don't expect us to tell you, figure it out for yourself!"

I've used "vcenter_ovf_libraryitem" as an example to illustrate the deficiencies in the VCenter Rest Library Documentation but this is NOT the only module with these kinds of issues...pretty much every module has some documentation or example issues that fit into the above problems.

The entire documentation of this collection needs a serious overhaul. As it is right now the users of this module are basically having to figure it out for themselves with no guidance by your team...and while I can't say the documentation is actively HARMFUL to figuring out it's use, it is definitely UNHELPFUL in most cases and misleading in others.

ISSUE TYPE

• Documentation Report

COMPONENT NAME

ALL

ANSIBLE VERSION

ansible [core 2.11.5]
  config file = None
  configured module search path = ['/Users/dwagner/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /usr/local/Cellar/ansible/4.6.0/libexec/lib/python3.9/site-packages/ansible
  ansible collection location = /Users/dwagner/.ansible/collections:/usr/share/ansible/collections
  executable location = /usr/local/bin/ansible
  python version = 3.9.7 (default, Sep  3 2021, 12:37:55) [Clang 12.0.5 (clang-1205.0.22.9)]
  jinja version = 3.0.1
  libyaml = True

(Ansible version in this case is meaningless to this report).