<commit_before><commit_msg>Adding Docs Usecase Snippets Story<commit_after>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.

{'fraction_non_alphanumeric': 0.11604383253722955, 'fraction_numerical': 0.009272267490868222, 'mean_word_length': 4.266272189349112, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4503196', 'n_tokens_mistral': 983, 'n_tokens_neox': 886, 'n_words': 429}