User Experience

[lkingland]

User Experience Update

This is a discussion to identify the key areas of the user experience that will have the most impact per time spent. We have many issues related to the user experience already captured as issues, and many more which have been suggested. These issues can be subdivided into four broad categories: System Configuration, Terminal UI (TUI),
Documentation and Samples.

System Configuration

System Configuration is accomplished globally via the Global Configuration settings located in ~/.config/func/config.yaml, and by function-local settings in func.yaml (in addition to flags and environment variables, which are out of scope for this discussion). In order for these declarative configurations to be effective, they need to be discoverable both as subscommands and through a properly documented configuration file.

Subcommands

While settings available through func.yaml has nearly full coverage via the CLI, the Global Config settings do not yet have subcommands. Unfortunately there is a naming conflict with the func config subcommand, which is perhaps more accurately described as mutating a function's metadata. We can resolve this collision by slightly altering the command groups, adding the function metadata subgroup:

Primary Commands
  Create
  Deploy
  Describe
  Delete
  List

Metadata
  Envs
  Volumes
  Labels
  Git

System
  Languages
  Templates
  Repositories
  Config <-- Freed up for "Global Configuration get, set and list"

Other
  Completion
  Version

In addition to being accessible via subcommands, each needs to be confirmed to be properly integrating with the shell for autocompletion.

Commented Config Files

It is a common and expected usage pattern to look at a config file to discover how to configure a system in leau (or hopefully in addition to) reading the documentation. Therefore a heavily config files are a necessity.

The core problem here is that yaml simply does not support the desired behavior. According to the spec, comments should not convey any content information. At best some parsers will make the comment nodes available, but will often lose their exact position.

Unless we find a yaml parser which supports the desired behavior, or are willing to write one ourselves, the best we can do here is either a single large comment block at the head of the config file with docs and current default values (along with a warning that user comments will not be preserved), or a manually-created template (also with a warning about the user comments). The latter is a more onerous ongoing support burden, so the former is likely the best balance of time to benefit.

Terminal-based User Interface (TUI)

The initial implementations of func have relied on the traditional approach of favoring non-interactive commands which fail-fast with an intelligible error. While this is an important first step, it is important to recognize that the expected usage pattern of terminal tools has evolved to place more emphasis on rich user experiences in the terminal. It may even be argued that, in the context of an interactive terminal, a full TUI should be the default. However, accepting this expectation should not interfere with the initial workflow, since it is essential for command composition and scripting. A hybrid approach is needed which will cause the least consternation. This can be accomplished by having a default interactive initial configuration where the default can be altered along with retaining a default to noninteractive when there is no attached TTY.

Initial Configuration

When a user runs func for the first time, interactivity will be presumed. We detect this first-run by the lack of a global config file. The user would be presented with three options:

Configure now
Continue without configuring (configure later)
Continue and don't ask again

In the first case, we interactively collect global configuration options, one of which being whether the user prefers interactive terminals to default to the interactive TUI.

Additional questions for the global configuration include the important "Default Registry" as well as verbosity, etc.

With this initial configuration defaulting to an interactive terminal approach, a user wishing to opt out of the TUI and use the fail-fast, noninteractive system can do so easily.

If the user does not create a global config file, such as choosing one of the "without configuring" options, the system would continue with the interactive approach, which can be disabled via a flag.

Experience Update

All of the individual command should be reachable from the root, and should be updated to include the most common expected use-cases.

Unless interactivity has been disabled, the default operation for a command is to enter into interactivity. In this case, to see full documentation it is necessary for the user to explicitly pass the --help flag.

Documentation and Samples

As the commands are being updated, a parallel task will be to update the Functions documentation. This will include not just a minor update, but a fairly extensive restructuring, along with callouts to sample functions kept in the func-samples repository which will illustrate various concepts in practice.