Developer experience improvement (DX initiative)

mavimo commented 5 years ago

Hi guys, there are some "bug" on user experience and I'll like to fix it, but before start I think we should find a solution that should match the expectation of much people as possibile.

Command consistency

As end-user there are command that are not consistent on usage, some time we use flag, some time we need to user args, eg:

hetzner-cloud context delete use arg do indicate the name of context to delete
hetzner-cloud ssh-key delete use flag do indicate the name of ssh-key to delete
hetzner-cloud cluster delete use flag do indicate the name of cluster to delete

Same for

hetzner-cloud context add use arg do indicate the name of context to add
hetzner-cloud ssh-key add use flag do indicate the name of ssh-key to add
hetzner-cloud cluster add use flag do indicate the name of cluster to add

etc.

Maybe we should define the standard behaviour we will like to use and refactor other commands in order to be consistent.

Debug mode

There is a --debug flag defined on the root command but other command do not honor it, maybe we should allow all command to use this information when required.

Command listing

The hetzner-cloud list only the first level command, so user should enter in each command to detect the list of available subcommand, maybe we should list all command we have as doc? Something like:

A tool for creating and managing kubernetes clusters on Hetzner Cloud.

Usage:
  hetzner-kube [command]

Available Commands:
  cluster     view and manage kubernetes clusters, include subcommands:
     - add-external-worker    adds an existing server to the cluster
     - add-worker             add worker nodes
     - addon                  manages addons for kubernetes clusters
     - create                 creates a cluster
     - delete                 removes a cluster and deletes the associated nodes
     - kubeconfig             setups the kubeconfig for the local machine
     - list                   lists all created clusters
     - master-ip              get master node ip
     - remove-external-worker remove an external worker from node list

  completion  Generates bash completion scripts

  context     view and manage contexts, include subcommands:
     - add         adds a new context
     - current     prints the current used context
     - delete      deletes a new context
     - list        lists all contexts
     - use         switches to a saved context given by NAME

  help        Help about any command

  ssh-key     view and manage SSH keys, include subcommands:
     - add         adds a new SSH key to the Hetzner Cloud project and local configuration
     - delete      removes a saved SSH key from local configuration and Hetzner Cloud account
     - list        lists all saved SSH keys

  version     prints the current version

Flags:
      --config string   config file to use
  -d, --debug           debug mode
  -h, --help            help for hetzner-kube

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

And also command are not listed by priority (eg. version, help and completion are less relevant that other commands).

@xetys @JohnnyQQQQ @gadelkareem @voron @pierreozoux @cice @dsteiman @lilvinz @eliasp @Baughn @MartinNowak @zozo @felixonmars @quorak @lfrancke @kabudu @meMo-Minsk @pushthat @jcassee @Zebradil @namxam @eliasp @hojerst @thordin9 @exocode @torgon @EamonKeane @kabudu @rvasilev any opinion? (sorry if I ping you, but as reported above having large feedback should be the first step here :D )

PS: maybe some other DX issue are missing, please report it and I'll update this doc ASAP.

gadelkareem commented 5 years ago

Thanks @mavimo for this proposal. I agree that there is inconsistency with the command structure, but I see this often in packages that are in the early development phases, which should eventually be refactored.

I needed the debug mode to dump a log file so I used the --debug flag in https://github.com/xetys/hetzner-kube/pull/231 but it is still not available for all commands

jcassee commented 5 years ago

@mavimo I'm not a heavy hetzner-kube user, but my $0.02:

All good ideas. The documentation looks helpful.

And also command are not listed by priority (eg. version, help and completion are less relevant that other commands).

Ordering by priority feels like a good idea.

About command consistency, I think many people using hetzner-kube will be familiar with kubctl, so we could take inspiration from it. The command structure is also pretty consistent.

xetys commented 5 years ago

I am totally fine with this proposal. I will add it to our v1.0.0 project.

Zebradil commented 5 years ago

I'm not using the tool currently, so don't take my opinion too seriously, but I completely agree on the first two points:

I'd prefer using arg instead of flag for essential parameters
It'd be great to have consistent behaviour for --debug flag

According the help message. I'd like to see extensive help only if there are only a few options and variations of subcommands. In the other case it makes sense to avoid distraction by hiding help info for subcommands in their own help messages. If I want to see the whole documentation I use man. For me the ideal documentation of command line tool is described as follows:

command help shows a complete description for the tool, a list of global flags in alphabetical order and a list of subcommands in alphabetical order; each item in the list is provided with a short description.
command subcommand help shows information for the subcommand in the same way described above (a complete description of the subcommand, subcommand global flags and sub-subcommands);
continue the same on each step down in subcommand hierarchy.

Zebradil commented 5 years ago

Just to clarify why I prefer alphabetical order instead of priority order.

alphabetical order:

always consistent
easy to find a needed line

priority order:

could be subjective (not always clear if command is more important than an other)
hard to find a needed line
useful for beginners, who doesn't know where to start (though, it should be covered in man pages or online docs)

mavimo commented 5 years ago

@Zebradil thx for info you share with us; about using man I'm not sure it's the right approach since this is a single executable binary that will be installed via:

wget http://... -o /usr/local/sbin/hetzner-kube
chmod +x /usr/local/sbin/hetzner-kube
/usr/local/sbin/hetzner-kube ...

So there is no setup process as we have via RPM / DEB / Windows Wizard, so I'm not sure have man page should be useful (is not "wrong" but I think is a feature that can be useful as "extra").

About command sorting you're right, is not easy to detect what command should be "on top" but I think some commands as "less useful" (eg help, completion or version, and yes, it's absolutely subjective 😄 ) and can be moved "at the end", but is not easy define order for other commands.

Maybe we can consider to split commands in two "macro section" (operational & utility) and then -for each of this section- add command in alphabetical order?

@jcassee 👍 to use args as kubectl since most of our users will become from this tool, so have the same "approach" I think should be the best approach to give users a good experience.

xetys / hetzner-kube