Story

Instead of requirements/design documents, we use user stories, or as shorthand, “stories”. A story is a short, user-centric description of a piece of functionality. You can see examples in our issue tracker here: https://www.pivotaltracker.com/s/projects/646869

Creating a new story
The convention is to post to the mailing list with a subject line “NEW STORY: whatever”. In your email, write your story, following these tips:


 * Make it user-centric, and speak in the first person: “When I do X, I want it to Y”
 * Keep it short. If it’s longer than a paragraph or two, it probably needs to be broken up into multiple stories.
 * Don’t talk about implementation or the technicalities of the design (that comes later in the task breakdown)
 * Refer to dependencies if appropriate (“Note: this should probably happen after…”)

Sometimes stories come in via the issue tracker (especially from people who are familiar with other open source projects but not with ours). If this happens, they should be forwarded to the mailing list for discussion.

Turning a story into something actionable
There’ll most likely be some back-and-forth on the mailing list talking about the story and adjusting it. Once this has settled down and consensus has been reached, the story should be added to the issue tracker, most likely by one of the current Coaches.

The next step is to discuss the steps/tasks needed to implement the story. The result of this should be an ordered lists of steps required, possibly supplemented by design notes/visual aids.

Finally, the story should have a set of “acceptance tests”, meaning a list of criteria which, if met, will mean that the task has been successfully completed.

Checklist for actionable stories
For a story to be actionable (i.e. appropriate for someone to work on) it should contain the following:


 * Clear, user-centric description of what’s desired
 * A task breakdown that developers/whoever can follow
 * A description of the success criteria (aka acceptance tests) – if these are met, the task is done!
 * An estimate of the size of the work (small/medium/large)
 * Other tags as appropriate