Standard UI terminology

The user interface (UI) term used in this section as a collective term and refers to:

• Web user interface (WebUI)

• 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 Inline elements for details.

• Format code snippets as standalone literal blocks. See Code samples 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.

• Depending on whether you describe CLI actions in the running text or in procedures, consider the following usage:

  In running text

  Do not use	Use
  The following is an example of using contrail-status to show the status of the new process	The following is an example of using the contrail-status to show the status of the new process
  The service can be used to start, stop, and restart the new services.	The service command can be used to start, stop, and restart the new services.

  
  

  In procedures

  Do not use	Use
  Switch off the VM by running the restart command.	Switch off the VM by running restart.
  Switch off the VM by running restart command.	Switch off the VM by running restart.

Web user interfaces guidelines

When documenting WebUI, use the following guidelines:

• Write the names of the UI elements exactly as they appear, including punctuation.

• Use the :guilabel: RST markup for all graphical and web UI elements.

  Example: Click OK.

• When describing a procedure in the 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 Nodes tab, click Add Nodes.

• Use the following standard UI terminology when describing WUI:

  Standard UI terminology: Verbs

  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.

  
  

  Standard UI terminology: Nouns

  Term	Meaning
  Field	An area in the WebUI 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 WebUI 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 as a reference.

This documentation, is a derivative of Writing style by OpenStack, used under CC BY.