Open Stack

Dear Product team,

based on the recent discussions on the "gap analysis template", I'd like to trigger some discussion on the terminology we are using:

We use the term "user story" for the whole document, but we also use the term "user stories" for the individual bullet points in the "use cases" section of the template [3]. In addition, the template talks about "The title of your use case" and inside we have a section "use cases" (plural).

This is quite confusing as we are mixing the terms "user story" and "use case" in singular/plural in different places.
I have already seen multiple occasions where this has led to misunderstandings in discussions (e.g. see line 35 in [2]) .
Conceptually, 
  a) the sentences we have in the section "use cases" are the real "user stories". [1]
  b) a "user story" is something different than a "user story", but on a similar level, so the title of that section is already misleading. [1]
  c) the whole document could be seen as a "requirement specification".

Simple solution:
- change from "user story" to "use case" (like also the title of the template is indicating). This would mean we have a "use case tracker" and it would also require few changes on the Wiki page.
- keep the term "user stories" for the user story sentences.
- change the section from "use cases to "Requirement specifications"

Of course we could also discuss about a more "complete" solution, where we revisit all terms used and change to e.g. "requirement specification" for the whole document (e.g. "baremetal requirement specification").

What do you think?

Best regards,
Gerald


[1] https://en.wikipedia.org/wiki/User_story#Comparing_with_use_cases
[2] https://etherpad.openstack.org/p/template_gap_and_overlap_analysis 
[3] https://github.com/openstack/openstack-user-stories/blob/master/user-story-template.rst