xmcli built-in help and online documentation

I would agree with you dynamox. This is a pain point in providing knowledge transfers at times.I have been bitten by values that are listed as not mandatory, being needed for the command to run and I think a better explanation like you have in the SE guides would improve the CLI portion of the user guide significantly. To provide all of this explanation and examples, it might be useful to separate the CLI documentation into its own document as well.

thank you.  I am all about learning new ways of doing things but seems as if the help menu was written by an engineer and not by a technical writer. While i could play around and figure out how to assign tags, i am very hesitant do it with with commands that can do some real damage.

So Avi, how do we relay this feedback to the mothership in Hopkinton ?  Any feedback from you side ?

dynamox wrote: thank you.  I am all about learning new ways of doing things but seems as if the help menu was written by an engineer and not by a technical writer. While i could play around and figure out how to assign tags, i am very hesitant do it with with commands that can do some real damage.

Very true - the help is (normally) great if you already know what you're doing and just need to know the option names, but not overly helpful if you're trying to learn how to use a command.  The "tag" syntax that you've shown is definitely one of the worst as it's not even clear what the options are - I thought we called these out in the Users Guide but I just realized that we don't so I'll make sure that we get that fixed!

For that specific command, you can get a list of valid "entity" values by passing in an invalid one, in which case you'll get this error :

** Error: Command Syntax Error: entity property must have one of the following values: [InfinibandSwitch, DAE, Initiator, BatteryBackupUnit, Scheduler, StorageController, DataProtectionGroup, X-Brick, Volume, Cluster, InitiatorGroup, SSD, SnapshotSet, ConsistencyGroup, Target]

From that, you can probably work out that the command you need is something like :

tag-object entity="Volume" entity-details="MyVolume" tag-id="/Volumes/MyTag"

(show-tags will give you the exact value for the tag-id - you can't just use the raw tag name.  And I hate to say it, but the entity= value is case sensitive - "volume" will not work, only "Volume")

Of course, it shouldn't be that difficult, and I'll make sure that as at least a first step we get the users guide updated to be a little more user friend...

If you've got specific examples of things that are wrong (echolaughmk - especially those you mentioned that showed options as not being mandatory where they were) then feel free to drop me an email as things like that can be fixed fairly easily.

The real solutions - better documentation for the CLI (and the REST API, which is what you really should be using if you're attempting to automate anything), and even a better CLI overall, are things that we're working towards - they will happen, but as with everything it's just a matter of priorities...

while i understand the whole shift to REST API, i am not there yet.  Smaller tasks are much simpler to automate with bash/perl (at least for me).  So please do not discriminate against the CLI, if you provide that capability it needs to be well supported and documented.

I can eventually "work out" how to do things in xmcli but i shouldn't have to. Your tech writers should look at Solutions Enabler manuals as the gold standard, those guys/gals have their stuff together. At this point XtremIO has been around a while, expectations are higher.

HI Scott,

I can do that if you want to shoot me a private message with your email. In my case, it was the power-off command during a planned shutdown where it said the cluster-name wasn't mandatory (had a NO in the column), but the command would fail without it.

I understand it is a dynamic product and I would agree with dynamox on the SE manuals as the gold standard (former EMC and Symm member) so any improvements to the docs would be greatly received by the field and customers.

-Keith

Thanks for the feedback folks. We will take it back to the documentation team.