Please take a few minutes and answer a couple of questions regarding the plug-ins documentation.
- Do you think that the API reference information is valuable in the form of tables in the documentation?
- Do you find the information in the vCO API Explorer enough?
- API scripts
- Use cases
- API scripting
- Other (please describe)
Hopefully, your feedback would help us to improve the plug-ins documentation.
vCO documentation team
Here we go:
Was the plug-ins documentation helpful in achieving your tasks with the product?
Not really, it's mostly repetition of the Workflows, no background information (only exception: the small chapter about vCloud Director Plugin components, page 7) given. The documentation contains mostly a description of the Workflows (which are usually very straight forward to operate).
I would like to see much more background information, more WHY to do this, not only WHAT to do.
So a section about a typical "getting started" was useful:
- Install the plugin
- run the workflow X to do ..... Then you have setup your .....
- now run workflow Y to ......
- now you have build a typical environment, and can start developing your own customer workflows using the plugin.
Where do you look for API scripting information?
API Explorer is enough!
(repeating the same information in tables (or even a javadoc-html-format as available for the vCenter-Plugin) only rises the risk of old/different information.
Just make sure that the API-Explorer information is accurate, complete and current.
What would you use when you create custom workflows?
However, it depends on the quality of the actions: I've worked in some environments where it's policy NOT to use existing stuff, only by copying it to own modules (where youself are responsible for updates)
(Bad) Example: A lot of Actions in the vCenter plugin have lots of internal references to other actions, so the dependencies are not visible. And there are also some Actions which do not provide complete functionality.
So: Provide actions with high quality (on "low level"). One atomic action per task. Divide between library actions ("driver"-like), and higher-level actions which call other ones.
(Same affects here as well:)
What type of examples would be most valuable for you?
Full examples based on real-world use-cases give a good introduction, what's possible with the plugin at all. Good Example: "Library / vCloud High Level / Setup new cloud cell"
Scripting examples are also important, they speed up the development of custom scripts dramatically (otherwise you have to do a lot of research in API Explorer or existing Actions)
Important: Make a clear distinction between:
- High Level Workflows intended to be used by a (human) user
- "Setup" workflows (like the "Library / SOAP / Configuration" ones)
- Workflows only containing scripting examples
- (mostly very atomic and generic) "library" workflows which are mainly used within other workflows
Bad Example: Again in vcenter plugin (sorry 😞 The dozens of "Clone Virtual Machine"-workflows, some are not usable by human (because of properties as input parameter), some are mostly redundant, some are missing (e.g. clone from a specific snapshot), and some are just not working properly (the sysprep stuff is hard to used correctly)
I know, not all of these "requests" are for the documentation team, but also for the plugin developer themself, but I'm sure you will negotiate it :smileysilly: .
And: It's not that bad as it sounds, I'm very happy to see more and more vCO-plugins being available!!
www.vcoportal.de - Orchestrate. Your Cloud.