Adding Docs Usecase Snippets Story

Adds a new user story for the addition of usecase
snippets within the user/operator documentation.

Change-Id: I190fd9fa8496f01c19de96b2238696ffc37d789c

user-stories/proposed/doc-usecase-snippet.rst

@@ -0,0 +1,90 @@
+Add Use Cases to Code Snippets in Docs
+======================================
+
+Cross Project Spec - None
+
+User Story Tracker - None
+
+Problem Description
+-------------------
+
+
+*Problem Definition*
+++++++++++++++++++++
+Operators have noted that it is easier to learn the commands associated with
+the different OpenStack projects if examples, or usage snippets, were provided
+for specific usage patterns. Some of the specific feedback we heard from
+operators was:
+
+* “You could add examples to the output of the CLI help commands, but I don't
+  think there was ‘anything that was unclear’ enough, and that might actually
+  contribute to too much help clutter.”
+* “Adding more examples in the documentation.”
+* “It is a good client, adding examples to the help would be very helpful.”
+
+The use case-based snippets provide two benefits to both operators and
+application developers.  First, the snippets help users understand how code
+is structured for the various OpenStack projects.  In addition, users are able
+to re-use the snippets for their own needs.  This is why the snippets should
+be based on common use cases.
+
+Opportunity/Justification
++++++++++++++++++++++++++
+Use case-based snippets can significantly reduce the learning curve
+associated with learning both the commands and structure associated for
+the various projects.  For example, operators mentioned during the
+OpenStackClient usability studies in both Austin and Barcelona that it took
+time to learn the command structure.  However, they were able to efficiently
+use the client once they became familiar with the structure.
+
+Use Cases
+---------
+
+User Stories
+------------
+These user stories utilize the standard `OpenStack UX Personas`_.
+
+* As `Rey the Cloud Operator`_, I would like to quickly learn commands and
+  structure associated with each project. In addition, I would like to have
+  snippets for common use cases that I can modify for my own purposes.
+.. _Rey the Cloud Operator: http://docs.openstack.org/contributor-guide/ux-ui-guidelines/ux-personas/cloud-ops.html
+.. _OpenStack UX Personas: http://docs.openstack.org/contributor-guide/ux-ui-guidelines/ux-personas.html
+
+Usage Scenario Examples
++++++++++++++++++++++++
+#. Rey has decided to explore the OpenStackClient (OSC) as an alternative to
+   using the individual APIs
+#. Rey opens the OpenStack documentation page
+#. Rey opens the new Use Case chapter (page) and sees several snippets of
+   code based on common use cases
+#. Rey now understands how the commands and structure are used to
+   complete common tasks
+
+Note: The best analogy seems to be to learning to read.  A dictionary and an overview
+of language structure is useful.  However, actually seeing both words and structure
+used in a sentence ties everything together in a meaningful way.
+
+
+Related User Stories
+++++++++++++++++++++
+None.
+
+*Requirements*
+++++++++++++++
+None.
+
+*External References*
++++++++++++++++++++++
+* `Operator OpenStackClient Validation Study (Barcelona 2016)`_
+* `Operator OpenStackClient Validation Study (Austin 2016)`_
+
+.. _Operator OpenStackClient Validation Study (Barcelona 2016): https://docs.google.com/presentation/d/1K-XImqK4-ODUvA1dr9t2LiUGib54MMKh1ANJJ2pldhU/edit?usp=sharing
+.. _Operator OpenStackClient Validation Study (Austin 2016): https://docs.google.com/presentation/d/19ef_3mG9p_G2ZsUcgTAj9hmOynxL5LAyQD7KlXIbYBU/edit?usp=sharing
+
+*Rejected User Stories / Usage Scenarios*
+-----------------------------------------
+None.
+
+Glossary
+--------
+None.