Jump to: navigation, search

UnifiedCLI/HumanInterfaceGuidelines

< UnifiedCLI
Revision as of 17:32, 26 April 2012 by Dtroyer (talk)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)


#!rst
OpenStack CLI Human Interface Guidelines
****************************************

Overview
========

What is a HIG?
The Human Interface Guidelines document was created for OpenStack designers in order to direct the creation of new
OpenStack command interfaces.


Principles
==========

The principles established in this section define the high-level priorities to be used when designing and evaluating
interactions for the OpenStack command line interface. Principles are broad in scope and can be considered the philosophical
foundation for the OpenStack experience; while they may not describe the tactical implementation of design, they
should be used when deciding between multiple courses of design.

A significant theme for designing for the OpenStack experience concerns focusing on common uses of the system
rather than adding complexity to support functionality that is rarely used.

Consistency
-----------

Consistency between OpenStack experiences will ensure that the command line interface feels like a single experience instead of a
jumble of disparate products. Fractured experiences only serve to undermine user expectations about how they should
interact with the system, creating an unreliable user experience. To avoid this, each interaction and visual
representation within the system must be used uniformly and predictably. The architecture and elements detailed in
this document will provide a strong foundation for establishing a consistent experience.

Example Review Criteria
~~~~~~~~~~~~~~~~~~~~~~~

* Do the command actions adhere to a consistient application of actions?
* Has a new type of command subject or output been introduced?
* Does the design use command elements (options and arguments) as defined? (See Core Elements.)
* Can any newly proposed command elements (actions or subjects) be accomplished with existing elemetns?

* Does the design adhere to the structural model of the core experience? (See Core Architecture.)
* Are any data objects displayed or manipulated in a way contradictory to how they are handled elsewhere in the core experience?

Simplicity
----------

To best support new users and create straight forward interactions, designs should be as simple as possible. When
crafting new commands, designs should minimize the amount of noise present in output: large amounts of
nonessential data, overabundance of possible actions, etc. Designs should focus on the
intent of the command, requiring only the necessary components and either removing superfluous elements or making
them accessible through optional arguments. An example of this principle occurs in OpenStack’s use of tables: only the
most often used columns are shown by default. Further data may be accessed through the output control options,
allowing users to specify the types of data that they find useful in their day-to-day work.

Example Review Criteria
~~~~~~~~~~~~~~~~~~~~~~~

* Can options be used to combine otherwise similar commands?

* How many of the displayed elements are relevant to the majority of users?
* If multiple actions are required for the user to complete a task, is each step required or can the process be more efficient?

User-Centered Design
--------------------

Commands should be design based on how a user will interact with the system and not how the system’s backend is
organized. While database structures and APIs may define what is possible, they often do not define good user
experience; consider user goals and the way in which users will want to interact with their data, then design for these
work flows and mold the interface to the user, not the user to the interface.

Commands should be discoverable via the interface itself. FIXME(dtroyer): more on help here

Example Review Criteria
~~~~~~~~~~~~~~~~~~~~~~~

* How quickly can a user figure out how to accomplish a given task?
* Has content been grouped and ordered according to usage relationships?
* Do work flows support user goals or add complexity?

Transparency
------------

Make sure users understand the current state of their infrastructure and interactions. For example, users should be
able to access information about the state of each machine/virtual machine easily, without having to actively seek out
this information. Whenever the user initiates an action, make sure a confirmation is displayed[1] to show that an input
has been received. Upon completion of a process, make sure the user is informed. Ensure that the user never
questions the state of their environment.

[1] This goes against the common UNIX philosophy of only reporting error conditions and output that is specifically requested.

Example Review Criteria
~~~~~~~~~~~~~~~~~~~~~~~

* Does the user receive feedback when initiating a process?
* When a process is completed?
* Does the user have quick access to the state of their infrastructure?


Core Architecture
=================

Basic Structure
---------------

The OpenStack client has three distinct parts to the command line (in order)::

* global options
* command action and subject
* command arguments and options

Output formats::

* user-friently tables with headers, etc
* machine-parsable delimited

Global Options
--------------

Global options are global in the sense that the apply to every command invocation regardless of 
action to be performed.  This includes authentication, API version selection.  Global options also
may be set via the environment.

All global options (as well as command options) begin with `--` (dash dash) followed by one or more lower case strings separated
by `-` (dash).

The environment variable name for a global option is derived by a) removing the leading `--`; b) converting
the option name to upper case; and c) replacing the remaining `-` (dash) chars with `_` (underscore).

All global options begin with `--os-`.  The corresponding environment variable begins with `OS_` to reduce
the potential for collisions with other existing environment variables.  If global options take precedence
over the corresponding environment variable when both are present.

Command Action and Subject
--------------------------

The majority of commands consist of an action (verb) and subject (noun).  Certain commands, such as `help`
deviate from this rule.

Specifically, the `help` command accepts an action and optionally a subject to select the proper output to display.

The subject names are always specified in command in their singular form.  This is contrary to natural
language use.
FIXME(dtroyer): auto-correct this in the client?

Command Arguments and Options
-----------------------------

Most commands have one or more arguments (aka positional arguments) that supply information required to
carry out the command.  Optional information is supplied with options following the same style as the global
options, without the corresponding environment variables.

Command Output
--------------

The usual command output is pretty-printed using the Python `prettytable` module.

A machine-parsable output format may be specified with the global option `--os-output-format`.
[FIXME(dtroyer): insert better option name here]  The machine-parsable
output is a line oriented character delimited format with the delimting character `|` which may be
changed with the global option `--os-output-char`.

Note that setting `--os-output-char=,` does not produce true CSV format; there are no headers and
string values are not quoted.  Certain characters are not good candidates for delimiters as they
may appear naturally in the command output data; these include `:` (colon) and `.` (period).

Help Commands
-------------

The help system is considered separately due to its special status among the commands.  Rather than performing
tasks against a system, it provides information about the commands available to perform those tasks.  The format
of the `help` command therefore varies from the form for other commands in that the `help` command is optionally
followed by an action and subject in order to provide more specific information on that command.


Examples
========

The following examples depict common command and output formats expected to be produces by the OpenStack client.

FIXME(dtroyer): the example output below is based on the existing clients, improve them!)

Authentication
--------------

Using global options::

    stack --os-tenant-name ExampleCo --os-username demo --os-password secrete --os-auth-url http://localhost:5000:/v2.0 show server appweb01
    +------------------------+--------------------------------------+
    |        Property        |                Value                 |
    +------------------------+--------------------------------------+
    | OS-DCF:diskConfig      | MANUAL                               |
    | OS-EXT-STS:power_state | 1                                    |
    | flavor                 | m1.small                             |
    | id                     | dcbc2185-ba17-4f81-95a9-c3fae9b2b042 |
    | image                  | 754c231e-ade2-458c-9f91-c8df107ff7ef |
    | name                   | appweb01                             |
    | private_address        | 10.4.128.13                          |
    | status                 | ACTIVE                               |
    | user                   | demo                                 |
    +------------------------+--------------------------------------+

Using environemnt variables::

    export OS_TENANT_NAME=ExampleCo
    export OS_USERNAME=demo
    export OS_PASSWORD=secrete
    export OS_AUTH_URL=http://localhost:5000:/v2.0
    show server appweb01
    +------------------------+--------------------------------------+
    |        Property        |                Value                 |
    +------------------------+--------------------------------------+
    | OS-DCF:diskConfig      | MANUAL                               |
    | OS-EXT-STS:power_state | 1                                    |
    | flavor                 | m1.small                             |
    | id                     | dcbc2185-ba17-4f81-95a9-c3fae9b2b042 |
    | image                  | 754c231e-ade2-458c-9f91-c8df107ff7ef |
    | name                   | appweb01                             |
    | private_address        | 10.4.128.13                          |
    | status                 | ACTIVE                               |
    | user                   | demo                                 |
    +------------------------+--------------------------------------+


Machine Output Format
---------------------

Using the default `|` separator::

    stack --os-output-format list server
    ead97d84-6988-47fc-9637-3564fc36bc4b|appweb01

Using `,` as a delimiter, mixing global options and environment varaibles::

    export OS_OUTPUT_CHAR=","
    stack --os-output-format list server
    ead97d84-6988-47fc-9637-3564fc36bc4b,appweb01
Retrieved from "https://wiki.openstack.org/w/index.php?title=UnifiedCLI/HumanInterfaceGuidelines&oldid=8744"