Simplify the user story template

[benfrancis]

The current template for submitting a user story in this repository has 11 text fields (plus optional attachments) to be completed in order to submit a user story.

User stories come from agile software development, with the goal of shifting the focus from writing about requirements to talking about them. A user story is meant to be a short simple description of a feature told from the perspective of the person who has the need, typically following the structure "As a < type of user >, I want < some goal > so that < some reason >". They are deliberately kept concise and informal to shift the focus to the discussion around the requirement, where the discussion is more important than whatever text is written.

The current user story template is the antithesis of this approach* and I would suggest it needs to be radically simplified.

The user story should ideally just be a single sentence (in the form above). GitHub issues lend themselves well to hosting the discussion around that requirement. That discussion may then lead to the definition of "acceptance criteria" which can be used as a test to verify that the requirement has been met. Detail can also be added by splitting a user story into multiple smaller user stories.

If there is a need for a formal requirements document (which in agile development would usually be replaced by an ordered backlog of user stories) then I would suggest those requirements should be derived from the discussion around the user story and the acceptance criteria that come out of that discussion.

The approach we took to writing a Use Cases & Requirements document in the Web Thing Protocol Community Group was to write a collection of user stories**, and then a set of functional requirements for the specification derived from those user stories. I would suggest something along these lines could work well.

A simpler user story template could significantly lower the barrier to contribution and help make sure that requirements are derived from a more diverse set of perspectives.

---

* I realise the idea was probably to split out the three parts of the user story structure to ensure that all three are completed, but the resulting 11 field form is quite intimidating for someone who just wants to jot down a need they have.

** In the Web Thing Protocol Use Cases & Requirements report the user stories come under the heading of "Use Cases". I now realise this is incorrect because (as already distinguished in this repository) user stories and use cases are not really the same thing.

[egekorkan]

There is actually 3 real fields to fill, which make up the sentence you are talking about. This is already a radically simplified version of the template we used to require. Other than the 3, there are fields to ask for details, get user information and link to use cases. Would you prefer to not have any fields (even optional ones) for the "details"?

[benfrancis]

There are still 7 mandatory fields. I just think it's over-engineered, which results in an intimidating looking form that will put people off contributing (it certainly puts me off).

By comparison, this is the template I've used in the past...

I don't see why a submitter needs to specify a separate title and identifier, a GitHub handle is automatically associated with a GitHub issue, and the who, what and why don't each need to be broken down into separate fields. If people want to provide more information or context they can just write it underneath.

I think it's fine if the separate Use Case template is more structured, because Use Cases are by their nature more detailed (though I'm not completely clear from the proposed requirements policy how user stories and use cases are intended to be used together.)

[mmccool]

Well, we can certainly simplify things if it would make sense. It would also be possible to format the User Stories in the documents in sentence form. For the record we had the single-sentence form before, discussed it, and concluded that breaking it apart and having places to provide more description was helpful for people unfamiliar with User Stories.

[mmccool]

I should also say that just because we are using the term "User Story" does not mean we are using Agile. Basically we just want to document the reason (why) we need each feature (what), and the stakeholder (who) wants it.

[mmccool]

Also, the (optional) details field was added when we realized that some of the sentences, taken out of context, were too difficult to understand, or too ambiguous. Ideally these should only be used when necessary, and should be short.