diff --git a/doc/contributor-guide/source/rst-conv/inline-markups.rst b/doc/contributor-guide/source/rst-conv/inline-markups.rst index ae3ae87413..9492bda99e 100644 --- a/doc/contributor-guide/source/rst-conv/inline-markups.rst +++ b/doc/contributor-guide/source/rst-conv/inline-markups.rst @@ -1,3 +1,5 @@ +.. _inline_elements_rst: + =============== Inline elements =============== @@ -95,6 +97,8 @@ A term that appears in the glossary. | | :term:`services `. | +------------------------+---------------------------------------------------+ +.. _gui_element: + GUI element ~~~~~~~~~~~ diff --git a/doc/contributor-guide/source/rst-conv/source-code.rst b/doc/contributor-guide/source/rst-conv/source-code.rst index 3ab0369ffd..3f57351dae 100644 --- a/doc/contributor-guide/source/rst-conv/source-code.rst +++ b/doc/contributor-guide/source/rst-conv/source-code.rst @@ -1,3 +1,5 @@ +.. _source-code: + ============ Code samples ============ diff --git a/doc/contributor-guide/source/writing-style.rst b/doc/contributor-guide/source/writing-style.rst index 9ae3997e41..58ff795516 100644 --- a/doc/contributor-guide/source/writing-style.rst +++ b/doc/contributor-guide/source/writing-style.rst @@ -16,4 +16,5 @@ throughout all technical publications. writing-style/word-choice.rst writing-style/openstack-components.rst writing-style/release-names.rst + writing-style/ui-terminology.rst writing-style/code-conventions.rst diff --git a/doc/contributor-guide/source/writing-style/ui-terminology.rst b/doc/contributor-guide/source/writing-style/ui-terminology.rst new file mode 100644 index 0000000000..4c141a45a8 --- /dev/null +++ b/doc/contributor-guide/source/writing-style/ui-terminology.rst @@ -0,0 +1,128 @@ +.. _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 elipses (...) 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: + + .. 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:`nova image-create` command to take a snapshot. + - You can use the :command:`nova 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 ` 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 `_ +as a reference. +