d89c666d24
Update a code-convention to use OpenStackClient as the example. Also update the ui-terminology doc to add a note about using OpenStackClient and not per-project CLI tools. Change-Id: I167c82f9aa2cc6140d68e61d47af4c0230fb33a6
133 lines
4.2 KiB
ReStructuredText
133 lines
4.2 KiB
ReStructuredText
.. _ui-terminology:
|
|
|
|
Standard UI terminology
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The user interface (UI) term used in this section as a collective term and
|
|
refers to:
|
|
|
|
* Graphical user interface (GUI)
|
|
* Web user interface (WUI)
|
|
* Command-line interface (CLI)
|
|
|
|
This section provides general guidelines on how to describe UI elements
|
|
together with the preferred verbs and nouns.
|
|
|
|
Command-line interface guidelines
|
|
---------------------------------
|
|
|
|
When documenting actions that readers must perform in a command-line interface
|
|
(CLI), use the following guidelines:
|
|
|
|
* Use the related RST directives for the inline commands, file names,
|
|
directories, options, and so on. See :ref:`inline_elements_rst` for details.
|
|
|
|
* Format code snippets as standalone literal blocks. See :ref:`source-code`
|
|
for details.
|
|
|
|
* When you provide an output of a command, consider if a user needs to see all
|
|
output or partial. If an output includes multiple lines, consider cutting
|
|
the output. Use ellipses (...) to show that the page displays a portion of
|
|
the output.
|
|
|
|
* Always use the OpenStack Client ``openstack`` for CLI commands rather than
|
|
per-project CLI tools such as ``nova``.
|
|
|
|
* Depending on whether you describe CLI actions in the running text or
|
|
in procedures, consider the following usage:
|
|
|
|
.. list-table:: **In running text**
|
|
:widths: 10 10
|
|
:header-rows: 1
|
|
|
|
* - Do not use
|
|
- Use
|
|
* - You can use the :command:`ping` to verify the network connection
|
|
between the two devices.
|
|
- You can use the :command:`ping` command to verify the network
|
|
connection between the two devices.
|
|
* - You can use :command:`openstack server image create` command to take a
|
|
snapshot.
|
|
- You can use the :command:`openstack server image create` command to
|
|
take a snapshot.
|
|
|
|
|
|
|
|
|
.. list-table:: **In procedures**
|
|
:widths: 10 10
|
|
:header-rows: 1
|
|
|
|
* - Do not use
|
|
- Use
|
|
* - Switch off the VM by running the :command:`restart` command.
|
|
- Switch off the VM by running :command:`restart`.
|
|
* - Switch off the VM by running :command:`restart` command.
|
|
- Switch off the VM by running :command:`restart`.
|
|
|
|
Graphical and web user interfaces guidelines
|
|
--------------------------------------------
|
|
|
|
When documenting GUI and WUI, use the following guidelines:
|
|
|
|
* Write the names of the UI elements exactly as they appear, including
|
|
punctuation.
|
|
|
|
* Use :ref:`the :guilabel: RST markup <gui_element>` for all graphical
|
|
and web UI elements.
|
|
|
|
**Example:** Click :guilabel:`OK`.
|
|
|
|
* When describing a procedure in the GUI and WUI, start a step with
|
|
the location in the UI. This helps the user unfamiliar with it
|
|
to quickly find the required element.
|
|
|
|
**Example:** In the :guilabel:`Nodes` tab, click :guilabel:`Add Nodes`.
|
|
|
|
* Use the following standard UI terminology when describing GUI and WUI:
|
|
|
|
.. list-table:: **Standard UI terminology: Verbs**
|
|
:widths: 10 30
|
|
:header-rows: 1
|
|
|
|
* - Term
|
|
- Meaning
|
|
* - Click
|
|
- An act of pressing and releasing of a mouse button.
|
|
* - Press
|
|
- An action that requires pressing a button (physically) on your
|
|
keyboard, a power button, and so on.
|
|
* - Type
|
|
- An act of pressing a key to type it into a text box, etc.
|
|
|
|
|
|
|
|
|
.. list-table:: **Standard UI terminology: Nouns**
|
|
:widths: 10 30
|
|
:header-rows: 1
|
|
|
|
* - Term
|
|
- Meaning
|
|
* - Field
|
|
- An area in the WUI or GUI where you need to enter information.
|
|
* - Dialog
|
|
- A pop-up window that appears after an action. Do not use `screen`.
|
|
* - Panel
|
|
- A toolbar or a control panel.
|
|
* - Pane
|
|
- An independent area in the WUI or GUI that you can scroll and resize.
|
|
* - Button
|
|
- A graphical or web element which executes an action when clicked.
|
|
* - Icon
|
|
- A graphical or web element that represents a shortcut to an action.
|
|
* - Tab
|
|
- A graphical or web element that groups a set of actions.
|
|
* - Wizard
|
|
- A dialog that walks a user through the sequence of steps to perform
|
|
a particular task.
|
|
|
|
|
|
|
|
|
For more details, use the `IBM Terminology <https://www-01.ibm.com/software/globalization/terminology/>`_
|
|
as a reference.
|
|
|