[ui-content-guidelines] Text guidelines for the UI

Adding structure and content for UI content
guidelines within the Documentation
Contributor Guide

Co-Authored-By: Gudrun Wolfgram <gmolson@us.ibm.com>
Change-Id: Ib315913a3149cc997be4e4f09fa67df626c07562
Implements: blueprint ui-content-guidelines

doc/contributor-guide/source/index.rst

@@ -31,6 +31,7 @@ Contents
    build-locally.rst
    blueprints-and-specs.rst
    json-conventions.rst
+   ui-text-guidelines.rst
    common/glossary.rst
 
 Search in this guide

doc/contributor-guide/source/ui-text-guidelines.rst

@@ -0,0 +1,39 @@
+.. _uitextguidelines:
+
+==================
+UI text guidelines
+==================
+
+User interface (UI) text guidelines are
+intended for designers, developers, or reviewers
+contributing content within OpenStack user interfaces.
+Use these text guidelines to ensure that the OpenStack interface
+is usable, consistent, and concise.
+
+
+.. toctree::
+   :maxdepth: 2
+
+   ui-text-guidelines/ui-text-capitalization.rst
+   ui-text-guidelines/ui-action-labels.rst
+   ui-text-guidelines/ui-error-messages.rst
+
+In addition to these resources, ensure you
+review the :ref:`stg_writing_style` section. The general
+writing style guidelines also apply to content in
+the user interface.
+
+Top Tips
+~~~~~~~~
+
+Use these tips and quick links to access UI text guidance reminders.
+
+* Avoid abbreviations, acronyms, and slang. Unless the abbreviation
+  is better known than the word it stands for or space savings is
+  critical.
+* :ref:`Write in active voice<write_in_active_voice>`
+* :ref:`Be clear and concise<be_clear_and_concise>`
+* :ref:`Write objectively<write_objectively>`
+* :ref:`Do not use contractions<do_not_use_contractions>`
+* :ref:`Eliminate needless politeness<eliminate_needless_politeness>`
+* :ref:`Use consistent terminology<use_consistent_terminology>`

doc/contributor-guide/source/ui-text-guidelines/ui-action-labels.rst

@@ -0,0 +1,43 @@
+.. _uiactionlabels:
+
+================================
+Use recommended UI action labels
+================================
+
+It is important to use consistent labels across an action.
+
+.. In progress...please add, remove, edit based on
+   what is applicable to OpenStack.
+
+.. list-table:: Common action labels
+   :header-rows: 1
+
+   * - Action label
+     - Typical Usage
+   * - ``Create``
+     - Creates a new object.
+   * - ``Delete``
+     - Destroys an existing object. Label can
+       include the object being deleted,
+       such as Delete Image.
+   * - ``Download``
+     - Transfers a file to a user's local system.
+   * - ``Edit``
+     - Allows data or values to be modified. Edit
+       does not imply the object is automatically
+       updated. In most cases, you still must update
+       in order for the change to occur.
+   * - ``Filter``
+     - Changes view to only include objects that
+       match the filter criteria.
+   * - ``Import``
+     - Includes objects from an external source.
+   * - ``Manage``
+     - Modifies existing object settings or options.
+   * - ``Save``
+     - Saves data entered when you create an object.
+   * - ``Update``
+     - Automatically changes the data of an existing object.
+
+
+

doc/contributor-guide/source/ui-text-guidelines/ui-error-messages.rst

@@ -0,0 +1,66 @@
+.. _uierrormessages:
+
+==========================
+Follow UI alert guidelines
+==========================
+
+Alerts, or messages, are important to inform users about progress
+that they make or problems that they encounter in the user interface.
+
+Use the following alert types:
+
+* Success
+* Info
+* Warning
+* Danger (Error)
+
+General alert guidelines
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+When writing alerts, follow these rules:
+
+* Be courteous and do not blame the user
+* Use present tense to describe conditions that currently exist, or
+  use past tense to describe a specific event that occurred in the
+  past
+* Keep sentences short but helpful
+* Adhere to the guidelines in the :ref:`stg_writing_style` section
+
+Alert structure for new danger (error) conditions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A danger alert, or error message, should help the user resolve the
+problem quickly so that they can continue making progress. Do not
+include an error if you can avoid publishing the alert by enhancing
+the code.
+
+#. State the problem clearly and briefly.
+#. If appropriate, explain why the user encountered the error.
+#. If possible, tell the user how to fix the problem. If further
+   information is needed, consider whether the documentation should
+   be enhanced.
+
+.. note::
+
+   API returns might not be specific enough to adhere to these
+   structure guidelines. Be as explicit as you can in stating the
+   problem and resolution.
+
+Alert examples
+~~~~~~~~~~~~~~
+
+Success
+ * Successfully created key pair %(name)s.
+ * Image successfully updated.
+
+Info
+ * Updating volume snapshot "%s"
+ * Creating volume "%s"
+
+Warning
+ * Policy check failed.
+ * Insufficient privilege level exists to view user information.
+
+Danger
+ * Unable to create the volume.
+ * Unable to retrieve the image.

doc/contributor-guide/source/ui-text-guidelines/ui-text-capitalization.rst

@@ -0,0 +1,77 @@
+.. _uitextcapitalization:
+
+========================================
+Follow UI text capitalization guidelines
+========================================
+
+Interface element labels use a combination of
+headline-style capitalization and sentence-style
+capitalization. It is important to apply these
+capitalization guidelines consistently to make
+the UI clear and succinct.
+
+Headline-style capitalization capitalizes every word in the text,
+except:
+
+* Articles, except as the first word (a, an, the)
+* Coordinating conjunctions (and, or)
+* Prepositions, except the first or last word
+* Infinitives (to, in, an)
+
+Examples of headline-style capitalization:
+Restore Defaults, Allocate to Project
+
+Sentence-style capitalization only capitalizes the first word in
+the text. Unless the word is a proper noun that must be
+capitalized.
+
+Example of sentence-style capitalization:
+Maximum number of downloads
+
+Capitalization style for common UI elements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Headline-style capitalization
+-----------------------------
+
+* Chart titles
+* Dialog box titles
+* Icon labels
+* Links used for an action or navigation
+* Menu items (both menu bar and context menus)
+* Menu titles
+* Page titles
+* Button labels
+* Section headings
+* Step titles
+* Table column headers
+* Tab titles
+* Table titles
+* Toolbar buttons
+* Window titles
+
+Sentence-style capitalization
+-----------------------------
+
+* Check box labels
+* Field labels
+* File names
+* Group box labels
+* Headings for groups of radio buttons or check boxes
+* Hover help text
+* Input hints
+* List box, drop-down list, and combination box entries
+* List box labels
+* Messages (information, warning, and error)
+* Page instructions or descriptions
+* Progress bar label
+* Radio button labels
+* Status bar text
+
+UI capitalization cheat sheet
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use this image to quickly view common capitalization styles:
+
+.. image:: ../figures/ui-text-cheatsheet.jpg
+      :alt: UI text cheat sheet

doc/contributor-guide/source/writing-style/general-writing-guidelines.rst

@@ -19,6 +19,8 @@ When in doubt about the spelling of a word, consult the
 `Merriam-Webster's Collegiate Dictionary` and the `IBM Style Guide
 <http://www.redbooks.ibm.com/Redbooks.nsf/ibmpressisbn/9780132101301?Open>`_.
 
+.. _write_in_active_voice:
+
 Write in active voice
 ---------------------
 
@@ -211,6 +213,8 @@ Also, ensure that you follow the documentation guidelines for titles.
 For more information,
 see http://docs.openstack.org/contributor-guide/rst-conv/titles.html.
 
+.. _be_clear_and_concise:
+
 Be clear and concise
 --------------------
 
@@ -218,6 +222,8 @@ Follow the principles of minimalism. If you can describe
 an idea in one word, do not use two words.
 Eliminate all redundant modifiers, such as adjectives and adverbs.
 
+.. _write_objectively:
+
 Write objectively
 -----------------
 
@@ -343,6 +349,8 @@ Avoid personification
 Do not express your fears or feelings in technical writing. Avoid
 the adverbs such as "probably", "hopefully", "basically", and so on.
 
+.. _do_not_use_contractions:
+
 Do not use contractions
 -----------------------
 
@@ -358,11 +366,15 @@ Generally, do not contract the words.
 | don't                  | do not             |
 +------------------------+--------------------+
 
+.. _eliminate_needless_politeness:
+
 Eliminate needless politeness
 -----------------------------
 
 Do not use "please" and "thank you" in technical documentation.
 
+.. _use_consistent_terminology:
+
 Use consistent terminology
 --------------------------