Bug 890328

(In reply to comment #0)
> Description of problem:
> missing help file for add quota:
> 
>    [RHEVM shell (connected)]# help add quota / help add cdrom / help add
> permission / help add glustervolume / help add permit
> 

1. you have accessed dynamic cli help, - resource individual (generic help also available see/do 'help COMMAND').

2. all of the mentioned resources are sub-resources and does not exist by themselves (what is documented in the main help/user guide), to obtain help topic you should provide the context for it:

[oVirt shell (connected)]# add permission 
cluster        datacenter     group          host           storagedomain  template       user           vm             vmpool    

e.g 

help add permission --datacenter-identifier XXX
help add permission --vm-identifier XXX
help add permission --vmpool-identifier XXX
etc...

[RHEVM shell (connected)]# add 
brick          cluster        disk           group          network        permission     quota          snapshot       tag            user           vmpool         
cdrom          datacenter     glustervolume  host           nic            permit         role           storagedomain  template       vm             


When pressing add <tab> I can see all the objects that mentioned in the bug description. 

I would add the following redirection:
help add X -> help add X  with context Y ( since Y is obvious in most cases ) 

For example: 

help add cdrom -> will be redirected to help add cdrom when vm identifier is passed.   
help add quota -> will be redirected to add quota when datacenter identifier is passed .

(In reply to comment #2)
> [RHEVM shell (connected)]# add 
> brick          cluster        disk           group          network       
> permission     quota          snapshot       tag            user          
> vmpool         
> cdrom          datacenter     glustervolume  host           nic           
> permit         role           storagedomain  template       vm             
> 
> 
> When pressing add <tab> I can see all the objects that mentioned in the bug
> description. 
> 
> I would add the following redirection:
> help add X -> help add X  with context Y ( since Y is obvious in most cases
> ) 
> 
> For example: 
> 
> help add cdrom -> will be redirected to help add cdrom when vm identifier is
> passed.   
> help add quota -> will be redirected to add quota when datacenter identifier
> is passed .

i can't make such assumption cause:

1. this is not always 1x1 relation (as in vm/cdrom).

2. it will be confusing for the user if in some cases he will be asked to
pass parent identifier and in other ones no.

[RHEVM shell (connected)]# add 
brick          cluster        disk           group          network        permission     quota          snapshot       tag            user           vmpool         
cdrom          datacenter     glustervolume  host           nic            permit         role           storagedomain  template       vm             

[RHEVM shell (connected)]# help add quota 

unknown error: not enough arguments for format string

[RHEVM shell (connected)]# help add cdrom

unknown error: not enough arguments for format string



[RHEVM shell (connected)]# help add vm

USAGE
  
  add <type> [base identifiers] [attribute options]
  
DESCRIPTION
......

Simon , 

Please advise if the difference between : help add vm and help add cdrom is clear from the error message above and if you think that the user will understand what he did wrong / what he suppose to do .

> Simon , 
> 
> Please advise if the difference between : help add vm and help add cdrom is
> clear from the error message above and if you think that the user will
> understand what he did wrong / what he suppose to do .

oded, 

i do agree that message should be reformatted, but your complain
is different from the original bug report ....

(In reply to comment #5)
> > Simon , 
> > 
> > Please advise if the difference between : help add vm and help add cdrom is
> > clear from the error message above and if you think that the user will
> > understand what he did wrong / what he suppose to do .
> 
> oded, 
> 
> i do agree that message should be reformatted, but your complain
> is different from the original bug report ....

We can use this busy then for changing the message to be more descriptive .

Micheal, 

The problem here is that the help comes in the context of a specific instance. Meaning if I want to get help on add quota on a data center, I have to provide a DC name. Why? Will the help for DC A will differ from the one of DC B?

The above is confusing, and if you remember I actually had to reach for you when I've prepared the CLI demo, and understand from you how to get help on these. 

Help should be intuitive since it's the entry point for a user, if help is not intuitive then you can't get to the really complex stuff. 

What I suggest is: 
If you do: 

help add -> you get global help on the add command, and instructions how to get help on any resource you can add.

help add permissions -> you get global help on the add permissions, with all the appropriate variations  

help add permissions --<resouce>-identifier you get help specific to an identifier or the same as before.  Don't even request (allow to omit) the actual identifier. Making 'help add permission --datacenter-identifier' a legal statement. 

That is a robust help mechanism. 

Reopening.

(In reply to comment #8)
> Micheal, 
> 
> The problem here is that the help comes in the context of a specific
> instance. Meaning if I want to get help on add quota on a data center, I
> have to provide a DC name. Why? Will the help for DC A will differ from the
> one of DC B?

it's not for the given DC (now), but to understand that you willing to see help,
for the DC permissions and not others ...., in future we can be showing different help for different DCs cause they may require different params.

> 
> The above is confusing, and if you remember I actually had to reach for you
> when I've prepared the CLI demo, and understand from you how to get help on
> these. 

you wouldn't have to if you would look at help, it's explaining this and even
give help examples/formats (see bellow).

> 
> Help should be intuitive since it's the entry point for a user, if help is
> not intuitive then you can't get to the really complex stuff. 

it is, obviously if you have relations between the objects you have to tell
which one you're refer to, and more than that help has this: (all you need is to look at it ...)

[oVirt shell (connected)]# help add

USAGE
  
  add <type> [base identifiers] [attribute options]
  
DESCRIPTION
  
  Creates a new object or adds existent
  
SUPPORTED HELP FORMATS
  
  - This help will list all available attribute options for given resource creation
    
    * format      - help add resource_name
    * example     - help add vm
  
  - This help will list all available attribute options for given subresource creation
    
    * format      - help add subresource_name --resource-identifier xxx
    * example     - help add disk --vm-identifier myvm


> 
> What I suggest is: 
> If you do: 
> 
> help add -> you get global help on the add command, and instructions how to
> get help on any resource you can add.

exist

> 
> help add permissions -> you get global help on the add permissions, with all
> the appropriate variations  

taking in account all possible permutations of the x:y:z * number-of-params,
it will produce not-human-readable chunk of text disconnected from context, 
this is doable but useless in my view cause people looking at concrete /help want concrete answers and not to read a book ...

> 
> help add permissions --<resouce>-identifier you get help specific to an
> identifier or the same as before.  Don't even request (allow to omit) the
> actual identifier. Making 'help add permission --datacenter-identifier' a
> legal statement. 

it's fair request to ask, but if tomorrow we will have different params for
different context, like: 

1. add permission --datacenter-identifier DC1 --x --y

2. add permission --datacenter-identifier DC2 --x --z

based on different type of the DC, it's won't work, - i'm taking in account this
possibility.

> 
> That is a robust help mechanism. 

statical-bind using assumptions can't be robust, it can work today, but may be broken tomorrow because of changed requirements at business logic as explained 
above.

i know that you used to work with static helps and such behaviour may sound a bit odd to you, but we have different use-case and much more complex
system,

just to give you example we using DOC formatted routines, i.e foo(X),
foo method is single method used in system to perform foo and X is parameters
holder, so we can add params there as we wont without breaking backward compatibility, and clients should be able consume foo(X) *always*, therefore 
help that you see does not make any assumption and does not depends on specific
sdk version.

> 
> Reopening.

*** Bug 890349 has been marked as a duplicate of this bug. ***

I think that user experience ( especially help and documentation  ) are very important when using CLI. I recommend to fix this issue to 3.2 .

(In reply to comment #11)
> I think that user experience ( especially help and documentation  ) are very
> important when using CLI. I recommend to fix this issue to 3.2 .

Oded,

Only difference between existent help and suggested change is *not* demanding
parent resource instance identifier as in [1], but only option defining it as in [2], but as i've explained in Comment 9, this won't work with future changes, 

is there anything else you would like to be changed?

[1] help add permission --datacenter-identifier MY-DC

[2] add permission --datacenter-identifier

I think that we should allow requests such as 
help add quota : it will be the same as help add quota --datacenter-identifier  ( which is obvious )
In case you have two valid options we can return common help on "add X" with all the appropriate variations  ( see also https://bugzilla.redhat.com/show_bug.cgi?id=890328#c8 )


(In reply to comment #12)
> (In reply to comment #11)
> > I think that user experience ( especially help and documentation  ) are very
> > important when using CLI. I recommend to fix this issue to 3.2 .
> 
> Oded,
> 
> Only difference between existent help and suggested change is *not* demanding
> parent resource instance identifier as in [1], but only option defining it
> as in [2], but as i've explained in Comment 9, this won't work with future
> changes, 
> 
> is there anything else you would like to be changed?
> 
> [1] help add permission --datacenter-identifier MY-DC
> 
> [2] add permission --datacenter-identifier

(In reply to comment #13)
> I think that we should allow requests such as 
> help add quota : it will be the same as help add quota
> --datacenter-identifier  ( which is obvious )
> In case you have two valid options we can return common help on "add X" with
> all the appropriate variations  ( see also
> https://bugzilla.redhat.com/show_bug.cgi?id=890328#c8 )
> 
> 

i've replied on this comment, did you saw my answer?

(In reply to comment #14)
> (In reply to comment #13)
> > I think that we should allow requests such as 
> > help add quota : it will be the same as help add quota
> > --datacenter-identifier  ( which is obvious )
> > In case you have two valid options we can return common help on "add X" with
> > all the appropriate variations  ( see also
> > https://bugzilla.redhat.com/show_bug.cgi?id=890328#c8 )
> > 
> > 
> 
> i've replied on this comment, did you saw my answer?

Generally speaking I think that we need to look at CLI from user perspective instead of developer / scientist perspective . "Help add cdrom" help page should not produce not-human-readable chunk of text as you said ,  we can think about common set of parameters / resemblance between the possible permutations and design this page accordingly. We can use the help of technical writers for this purpose , as we did before.

Closing old bugs. If this issue is still relevant/important in current version, please re-open the bug.