Help message is overwhelming for first time users

[rhuss]

[kind/Enhancement]

Which functionality do you think we should update/improve?

When calling odo without argument (typical usage for first time users), one get:

Error: Use one of available subcommands: app, catalog [options], component, config, create <component_type> [component_name] [flags], delete <component_name>, describe [component_name], help [command], link <service> --component [component] OR link <component> --component [component], list, log [component_name], login, logout, preference, project [options], push [component name], service, storage, unlink <service> --component [component] OR unlink <component> --component [component], update, url, utils, version, watch [component name]
Usage:
  odo [flags]
  odo [command]

Examples:
  # Creating and deploying a Node.js project
  git clone https://github.com/openshift/nodejs-ex && cd nodejs-ex
  odo create nodejs
  odo push

  # Accessing your Node.js component
  odo url create

Component Commands:
  component   Components of an application (create, delete, describe, get, link, list, log, push, unlink, update, watch)
  config      Modifies configuration settings (set, unset, view)
  create      Create a new component
  delete      Delete an existing component
  describe    Describe the given component
  link        Link component to a service or component
  list        List all components in the current application
  log         Retrieve the log for the given component
  push        Push source code to a component
  unlink      Unlink component to a service or component
  update      Update the source code path of a component
  watch       Watch for changes, update component on change

Other Commands:
  app         Perform application operations (delete, describe, list)
  catalog     Catalog related operations (describe, list, search)
  preference  Modifies preference settings (set, unset, view)
  project     Perform project operations (create, delete, get, list, set)
  service     Perform service catalog operations (create, delete, list)
  storage     Perform storage operations (create, delete, list, mount, unmount)
  url         Expose component to the outside world (create, delete, list)

Utility Commands:
  help        Help about any command
  login       Login to cluster
  logout      Log out of the current OpenShift session
  utils       Utilities for terminal commands and modifying Odo configurations (terminal)
  version     Print the client version information

Flags:
      --alsologtostderr                  log to standard error as well as files
      --complete                         Install completion for odo command
  -h, --help                             help for odo
      --log_backtrace_at traceLocation   when logging hits line file:N, emit a stack trace (default :0)
      --log_dir string                   If non-empty, write log files in this directory
      --logtostderr                      log to standard error instead of files (default false)
      --skip-connection-check            Skip cluster check
      --stderrthreshold severity         logs at or above this threshold go to stderr (default 2)
      --uncomplete                       Uninstall completion for odo command
  -v, --v Level                          log level for V logs. Level varies from 0 to 9 (default 0).
      --vmodule moduleSpec               comma-separated list of pattern=N settings for file-filtered logging
  -y, --y                                Don't prompt user for typing 'yes' when installing completion

Use "odo [command] --help" for more information about a command.

 ✗  Use one of available subcommands: app, catalog [options], component, config, create <component_type> [component_name] [flags], delete <component_name>, describe [component_name], help [command], link <service> --component [component] OR link <component> --component [component], list, log [component_name], login, logout, preference, project [options], push [component name], service, storage, unlink <service> --component [component] OR unlink <component> --component [component], update, url, utils, version, watch [component name]

Why is this needed?

• Is it an error to call odo without argument ? Couldn't this be a synom for 'help' ?
• Why is the error printed twice (at the top and at the bottom) ?
• Why is the error message so huge ? It's very confusing and not helpful at all imo.
• IMO there should be more examples, but below the commands so that the reference information is at the top. This would be similar to the ordering within man pages.

odo [flags]
odo [command]

suggests that you can either use odo with flags or with a command. This usage message is not very helpful

• The subcommand list behind the commands (e.g. component) with up to 11 subcommands is overwhelming and not very useful also, because its hard to read and destroy the layout.

• "Delete an existing component" vs. "Describe the given component" (shouldn't this be "Delete component" and "Describe component" (the shorter the better).

• "Modifies configuration settings" --> "Change or view configurtion" (i.e. the 'view' subcommand is not about modification).

• "Components of an application" --> "Manage components"

....

[kadel]

/kind enhancement
/priority high
/area UX

[prietyc123]

I spend some time to analyse the issue and here are my thoughts.

AFAIU odo UX should be sync with oc UX because both the client has the almost similar operation. So, I believe typing only odo in the terminal should not reflect any statement as mentioned above.

Expected Output:

$ odo
// Output should be similar to oc but in odo context

$ odo -h
// Currently whatever the output we are following

The subcommand list behind the commands (e.g. component) with up to 11 subcommands is overwhelming and not very useful also, because its hard to read and destroy the layout.

I really found some valid suggestions given by OP, However I don't see any valid reason to change the Subcommand list/format/indentation because this is a key feature of odo command shortcut. But still I am open to any suggestion.

"Delete an existing component" vs. "Describe the given component" (shouldn't this be "Delete component" and "Describe component" (the shorter the better).

+1, I am ok with this. @kadel and Team WDYT?

"Modifies configuration settings" --> "Change or view configuration" (i.e. the 'view' subcommand is not about modification).

+1, I would suggest to use local configuration operation and global configuration operation instead. In this way we can consume whole configuration related stuffs in a single description.

"Components of an application" --> "Manage components"

+1, Sounds good to me.

I guess some good amount of odo code will be changed. Right now I am not that comfortable to handle this within the GA time frame. It will be easy for someone who has good grip on odo code, to send a quick PR with the changes mentioned above.

[prietyc123]

/unassign @amitkrout

[rhuss]

I really found some valid suggestions given by OP, However I don't see any valid reason to change the Subcommand list/format/indentation because this is a key feature of odo command shortcut. But still I am open to any suggestion.

Why not just reserve this list for the help page of the subcommand ? I.e of a user does an odo --help and then sees

odo --help

...
component   Manage application components

and then does a

odo components --help

Available Commands:
  create      Create a new component
  delete      Delete an existing component
  describe    Describe the given component
  get         Get currently active component
  link        Link component to a service or component
  list        List all components in the current application
  log         Retrieve the log for the given component
  push        Push source code to a component
  unlink      Unlink component to a service or component
  update      Update the source code path of a component
  watch       Watch for changes, update component on change

which lists the components subcommands is much better than leave the user guessing what this huge (create, delete, describe, get, link, list, log, push, unlink, update, watch) appendix actually means.

So also, I suggest to test all your output against a maximum assume line length (like 120 is a typical width people often use).

And, as in this example I change component Components of an application help message to something more meaningful, too.

[amitkrout]

Seems @cdrage is going to take care of this issue.

[amitkrout]

/unassign @amitkrout
/unassign @prietyc123

[amitkrout]

/unassign @prietyc123