diff --git a/README.rst b/README.rst index 2792ce8..053cf0e 100644 --- a/README.rst +++ b/README.rst @@ -1,6 +1,5 @@ - -rking with OpenStack User Stories -================================================= +Working with OpenStack User Stories +=================================== This repository is working space for the `OpenStack Product WG `_ and contains user stories and their associated trackers. diff --git a/doc/source/images/agile_overview.jpg b/doc/source/images/agile_overview.jpg new file mode 100644 index 0000000..502d05f Binary files /dev/null and b/doc/source/images/agile_overview.jpg differ diff --git a/doc/source/workflow/taxonomy.rst b/doc/source/workflow/taxonomy.rst index 7b05f0a..b7fcd48 100644 --- a/doc/source/workflow/taxonomy.rst +++ b/doc/source/workflow/taxonomy.rst @@ -1,3 +1,48 @@ -===== -#TODO -===== +Product WG: Taxonomy Overview +============================= +The Product Working Group will help the community document requirements, in the form of user stories, for key barriers to adoption based on specific needs of special interests groups (SIGs) that are working as a part of the user committee organization. While we will also accept user story submissions from individual members, it is highly encouraged that you join a Working Group that shares your interest and submit as a part of the group. The main reason for encouraging this is because the group may already have plans that align to your needs and, if the user story resonates with the team, they can help it get greater visibility through the working group members. + +Here is a list of all of the working groups that exist today, you can visit their wiki page for more information: `https://wiki.openstack.org/wiki/Category:Working_Groups `_ + + +The purpose of this document is to share the taxonomy/hierarchy used by the Product Working Group for generating, categorizing, and tracking user stories. + +Agile Terms +----------- +The Product Working Group will follow agile terminology/methodology in a loose sense. It is therefore important to cover some basic agile terms and process information before describing our manifestation of an agile-like process. Please also keep in mind that most individuals and organizations tend to have *slightly* different interpretations of the concepts being discussed in this section, therefore do not consider this a definitive guide on themes, epics, user stories, features, etc. + +**Theme**: An area of focus (grouping of user stories/epics). It does not contain significant detail and is associated with a single product. Normally either theme or epic is the top-level artifact when describing requirements. A theme can span multiple sprints. + +**Epic**: An epic is generally a larger, more broader, user story. It may be the top level requirements artifact or can be one of many epics under a theme. An epic will generally span multiple sprints; the user stories that are generated from the decomposed epic are the items that belong within the product backlog or sprint. + +**User Story**: A user story can only belong to one epic at a time and can not span sprints. The user story generally captures what the user wants using a format that captures an actor/role, objective, and benefit/reasoning. This item is then broken into more-detailed tasks or features that describe the specific work that must be done to deliver the user story. Most product backlogs prioritized work using user stories as the operational unit of ‘work’ + +**Feature**: Feature is used by some as an alternative to user story and as an alternative to task by others. For our terminology overview, we will consider feature and task as interchangeable terms. Please see task for additional details. + +**Scenario**: A scenario usually expands upon the user story to describes examples how the user story might be be interpreted or how the requirement being described is experienced by the user. A good scenario can also act a way to validate that the goal of the user story was successfully achieved. + +**Task**: A task is a lower-level requirements item that captures a sub-unit, or step, that is necessary to complete a user story. Tasks are usually generated by the development team working on the user story. + +.. image:: /doc/source/images/agile_overview.jpg + +Good resources for additional information related to these terms: + +`http://www.mountaingoatsoftware.com/blog/stories-epics-and-themes `_ + +`http://www.romanpichler.com/blog/agile-scenarios-and-storyboards `_ + +Product WG Mapping +------------------ +The Product WG will leverage agile terms to communicate and this section provides additional information on how these terms will be mapped inside the OpenStack community. + +**Theme**: Themes will be very high-level categories that are agreed upon by the Product WG and OpenStack Foundation. Generally, the themes will be areas such as resiliency, availability, performance, scalability, UX, etc. + +**Epic**: Epics will be used to build topics within each theme that could be used to aggregate user stories. For example, in the "availability" theme, we could have an epic for "service processes" and all of the user stories related to making services such as cinder, nova, keystone, etc. "highly available" would fall under this epic. + +**User Story**: A user story can only belong to one epic at a time and *can* span sprints. The user story generally captures what the user wants using a format that captures an persona/role, objective, and benefit/reasoning. This item is then broken into more-detailed tasks or features that describe the specific work that must be done to deliver the user story. The Product WG tracker will track user stories. + +**Feature**: Feature is used by some as an alternative to user story and as an alternative to task by others. For our terminology overview, we will consider feature and task as interchangeable terms. Please see task for additional details. + +**Scenario**: A scenario usually expands upon the user story to describes examples how the user story might be be interpreted or how the requirement being described is experienced by the user. A good scenario can also act a way to validate that the goal of the user story was successfully achieved. The Product WG user story template requires an entry for usage scenarios to foster discussion of the user story. + +**Task**: A task is a lower-level requirements item that captures a sub-unit, or step, that is necessary to complete a user story. Tasks are usually generated by the development team working on the user story. In our case, blueprints/specs that are related to a user story will be considered tasks. diff --git a/user-story-template.rst b/user-story-template.rst index 7b05f0a..3ba0af6 100644 --- a/user-story-template.rst +++ b/user-story-template.rst @@ -1,3 +1,119 @@ -===== -#TODO -===== +.. + +This work is licensed under a Creative Commons Attribution 3.0 Unported License. +http://creativecommons.org/licenses/by/3.0/legalcode + +**Sections in** *italics* **are optional.** + +.. + This template should be in ReSTructured text. Please do not delete any + of the sections in this template. If you have nothing to say for a + whole section, just write: None. + For help with syntax, see http://sphinx-doc.org/rest.html + You can also use an online RST editor at rst.ninjs.org to generate proper RST. + +============================= + The title of your use case +============================= + +*Problem description* +--------------------- +.. + This section is optional. Please use it to provide additional details (if available) about your user story (if warranted) for further expansion for clarity. A detailed description of the problem. This should include the types of functions that you expect to run on OpenStack and their interactions both with OpenStack and with external systems. Please replace "None." with the problem description if you plan to use this section. + +None. + +User Stories +------------ +.. + This section is mandatory. You may submit multiple user stories in a single submission as long as they are inter-related and can be associated with a single epic and/or function. If the user stories are explaining goals that fall under different epics/themes then please complete a separate submission for each group of user stories. Please replace "None." with the appropriate data. + + A list of user stories ideally in this or a similar format: + + * As a , I want to so that + * ... + +None. + +Usage Scenarios Examples +------------------------ +.. + This section is mandatory. In order to explain your user stories, if possible, provide an example in the form of a scenario to show how the specified user type might interact with the user story and what they might expect. An example of a usage scenario can be found at http://agilemodeling.com/artifacts/usageScenario.htm of a currently implemented or documented planned solution. Please replace "None." with the appropriate data. + + If you have multiple usage scenarios/examples (the more the merrier) you may want to use a numbered list with a title for each one, like the following: + + 1. Usage Scenario Title + a. 1st Step + b. 2nd Step + 2. Usage Scenario Title + a. 1st Step + b. 2nd Step + 3. [...] + +None. + +Opportunity/Justification +------------------------- +.. + This section is mandatory. Use this section to give opportunity details that support why pursuing these user stories would help address key barriers to adoption or operation. + + Some examples of information that might be included here are applicable market segments, workloads, user bases, etc. and any associated data. Please replace "None." with the appropriate data. + +None. + +Related User Stories +-------------------- +.. + This section is mandatory. If there are related user stories that have some overlap in the problem domain or that you perceive may partially share requirements or a solution, reference them here. + +None. + +*Requirements* +-------------- +.. + This section is optional. It might be useful to specify additional requirements that should be considered but may not be apparent through the user story and usage examples. This information will help the development be aware of any additional known constraints that need to be met for adoption of the newly implemented features/functionality. Use this section to define the functions that must be available or any specific technical requirements that exist in order to successfully support your use case. If there are requirements that are external to OpenStack, note them as such. Please always add a comprehensible description to ensure that people understand your need. + + * 1st Requirement + * 2nd Requirement + * [...] + +None. + +*Gaps* +------ +.. + This section is optional. It might be useful to provide information in this section if there is already some functionality in OpenStack that might seem to fit your user story on the surface but, in reality, does not actually fulfill the needs of the user type or the objective. If you choose to complete this section, please be sure to include information about the gap AND why you believe the current functionality does not meet the requirement. Please replace "None currently known." with the appropriate data. This section can often be left with "None currently known." + It is the purpose of this working group and repository to use the use cases presented here to identify what the gaps are. + +None currently known. + +*Affected By* +------------- +.. + This section is optional. This section should be used for prior records of activity inside OpenStack related to this user story (bugs that need to be fixed, blueprints for prior attempts, etc.). If possible, please include links to the related specs, blueprints, or bug reports. Please replace "None." with the appropriate data. + +None. + +*External References* +--------------------- +.. + This section is optional. Please use this section to add references for standards or well-defined mechanisms. You can also use this section to reference existing functionality that fits your user story outside of OpenStack. If any of your requirements specifically call for the implementation of a standard or protocol or other well-defined mechanism, use this section to list them. + +Glossary +======== +.. + This section is optional. It is highly suggested that you define any terms, abbreviations that are not commonly used in order to ensure that your user story is understood properly. + +Provide a list of acronyms, their expansions, and what they actually mean in general language here. Define any terms that are specific to your problem domain. If there are devices, appliances, or software stacks that you expect to interact with OpenStack, list them here. + +Remember: OpenStack is used for a large number of deployments, and +the better you communicate your user story, the more likely it is to be considered by the project teams.easier it will be to implement. + +**reST** + reStructuredText is a simple markup language + +**TLA** + Three-Letter Abbreviation is an abbreviation consisting of three letters + +**xyz** + Another example abbreviation