[jira] [Created] (HAWQ-928) Improve user experience of command-line help for hawq CLI utilities

["Severine Tymon (JIRA)" <ji...@apache.org>]

Severine Tymon created HAWQ-928:
-----------------------------------

             Summary: Improve user experience of command-line help for hawq CLI utilities
                 Key: HAWQ-928
                 URL: https://issues.apache.org/jira/browse/HAWQ-928
             Project: Apache HAWQ
          Issue Type: Improvement
          Components: Command Line Tools, Documentation
            Reporter: Severine Tymon
            Assignee: Lei Chang


This is an umbrella jira that could be broken into smaller pieces if any of these improvements are deemed worthwhile/useful. While working with the HAWQ CLI, I've noticed some issues with the command help documentation:

1) The option used to obtain help is not consistent. Some commands (like hawq checkperf) only take the '-?' option, while others do not take '-?' but take '-h' or '--help'. Some do not take '-h' because there is already an '-h' option, typically to supply a hostname.
2) Large variations in style and depth of command line help-- some commands (like hawq check) are long, man page style help, while others only provide brief command usage (hawq config). 
3) Representations of command-line syntax are inconsistent. Some use <>, some use all caps to indicate user-provided values.
4) Indicating the default value would be helpful in some cases. For example, the --locale, --lc* options of hawq init. (We do provide detailed explanation in product docs, but would help if cli informed users where the defaults come from if these options are not specified.)
5) Outdated external references ("Report bugs to <pgsql-bugs at postgresql.org>", EMC download links, Greenplum and gpssh, gpssh) 
6) Very minor-- Inconsistent word choice, punctuation and spelling (capitalization).



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)