Merge "Adding Docs Usecase Snippets Story"
This commit is contained in:
commit
ef784d804c
|
@ -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.
|
Loading…
Reference in New Issue