seanh · February 20, 2025 15:51 · Jan 26, 2018 · Jan 26, 2018 · Jan 15, 2018 · Jan 14, 2018
diff --git a/user_stories.md b/user_stories.md
@@ -23,10 +23,40 @@ Reading list
 [jbrains]: https://web.archive.org/web/20120716060616/http://jbrains.ca/permalink/how-youll-probably-learn-to-split-features "J.B. Rainsberger on splitting features"
 [jbrains_example]: https://web.archive.org/web/20111231080154/http://www.jbrains.ca:80/permalink/three-steps-to-a-useful-minimal-feature "J.B. Rainsberger: Three Steps to a Useful Minimal Feature"
 
+Communication between those who want and those who build the software
+---------------------------------------------------------------------
+
+User stories are a kind of software requirements, and software requirements
+are communication between those who want the software and those who will build
+the software:
+
+```
+People who want the software                                    People who will build the software
+----------------------------                                    ----------------------------------
+- Customers                                                     - Developers
+- Users
+- Analysts                          <-- Requirements -->  
+- Domain experts
+- Non-developers in the business
+  or organization
+```
+
+There needs to be a balance between the two sides of this communication. If
+the people who want the software dominate too much you end up with unrealistic
+requirements and deadlines, and developers don't understand exactly what's
+needed. Developers end up **trading quality for features** trying to meet the
+unrealistic deadline. Features end up partially implemented. Developers make
+decisions on their own that users should have been involved in.
+
+The developers dominate they can end up not learning from users what the users
+need.
+
 
 User stories and agile
 ----------------------
 
+Use user stories as the center of your "home-grown story-drive agile process."
+
 Some Agile principles that user stories support (from [Mark Shead][]):
 
 * **Working software** is the primary measure of progress
@@ -53,6 +83,14 @@ The same goes for prioritising work with user stories. User stories are units
 that represent value to the customer. Working from user stories and delivering
 frequently minimizes project risk.
 
+From [User Stories Applied][]: **you can't predict a software development
+project**. Users have new ideas or change their minds when they see early
+versions. Developers can't estimate accurately. Instead, **make decisions
+throughout the duration of the project** instead of trying to make them all up
+front. Use user stories as a way to get information early and often, and to
+support iterative development. Write user stories at any time throughout the
+project.
+
 Who should write the user stories?
 ----------------------------------
 
@@ -154,16 +192,97 @@ Properties that user stories should have
 
 INVEST:
 
-1. Independent
-2. ...
+1. **I**ndependent.
+
+   As much as possible stories should be independent from eachother, meaning
+   that they could be developed in any order (or any subset of can be left
+   out for good).
+
+   Dependencies between stories complicate prioritization and planning, get in
+   the way of divvying up work between different developers.
+
+   Especially problematic if a high priority story depends on a low priority
+   one, or a low cost story depends on a high cost one.
+
+   Dependencies can also complicate estimation in cases where the order that
+   stories are implemented in affects how long each will take (it'll be much
+   quicker to do X after Y is done).
+
+2. **N**egotiable. A user story is a promise for a conversation. It should have
+   just enough detail, and detail should be added as late as possible.
+
+3. **V**alubable
+
+4. **E**stimatable
+
+   If it's **s**mall (see below) then I'm not sure that it needs to be
+   estimatable. Make stories small enough to do inside of one sprint. If the
+   story's in a state where we're confident it's small enough then that should
+   be good enough. No need to also put a silly estimate on it.
+
+5. **S**mall
+
+6. **T**estable: clear acceptance criteria, so that developers can know when
+   they're finished.
+
+How much detail? (And when?)
+----------------------------
+
+**Card, conversation and confirmation**: a user story (card) isn't a complete
+requirements or specification, it's **a placeholder for conversations** that
+will be had closer to the time of implementing ("a promise for a conversation").
+
+These conversations among the dev team and between the dev team and the people
+who want the software and their proxies) should be ongoing throughout the
+project, not all up front.
+
+GitHub issue comments, links to Slack discussions, etc work very well on GitHub
+issue user stories if you think of a user story as a placeholder for a
+conversation.
+
+**Defer adding detail** to a card until when you have the best understanding,
+which is as close to implementation time as possible. Don't pretend you can
+know and write down everything in advance. Also don't spend time thinking about
+a feature until you're positive it's needed.
+
+Before close to implementation time you _can_ use the card as a place to list
+**reminders** of things to discuss or think about during implementation.
+
+You can also add **notes** to a card earlier on and these notes can be used
+later to **resume the conversation** where it left off. To know how detailed
+the notes should be - it should be enough to resume the conversation later,
+even if the customer and user having the conversation are different people.
+
+Adding too much detail to a card shuts down active thinking and discussion
+about the card when it comes time to work on it later. Makes it look like
+everything is set in stone.
+
+### How to defer detail
+
+Things that enable deferring detail on user stories until close to
+implementation time:
+
+* Epics (split them up closer to the time), epic as placeholder for more
+  detailed stories it'll be split into later
 
 Adding detail to user stories
 -----------------------------
 
 * Splitting them into smaller ones adds detail
 * Adding acceptance criteria, notes, tests, links to further reading
+* Add reminders of things to discuss later or things to consider when implementing
 * Just the right amount of detail
 * Detail just in time
+* Keep the story itself, any notes, any tests, etc clearly separated into
+  separate sections so that the notes don't clutter the actual story
+
+For things that've already been decided you can add "**Test...**" notes to
+the card. E.g. "**Test with VISA, MasterCard and American Express** (it has
+already been decided that VIA MasterCard and American Express will be
+supported).
+
+Test notes can also work as reminders of things to consider: "**Test with
+expired cards**".
 
 Reading:
 
@@ -691,6 +810,11 @@ An epic is just a big user story. Too big to implement directly. They tend to
 come before the smaller user stories (it's easier to write the epics first).
 Can end up being split up into dozens or hundreds of user stories.
 
+Different types of epics:
+
+* **Compound stories**: can be split into smaller stories.
+* **Complex stories**: too much uncertainty. Split out a spike story.
+
 Tasks
 -----
 
@@ -704,3 +828,10 @@ Restricted to a single type of work (programming, testing, UI design, analysis,
 
 What developers break user stories down into. Task list on GitHub issue.
 "Task" GitHub label for standalone tasks.
+
+Spikes
+------
+
+* When there's too much uncertainty about a card, split a spike out of it
+* Don't put the spike and the subsequent implementation story in the same
+  sprint, too much uncertainty.
diff --git a/user_stories.md b/user_stories.md
@@ -1,14 +1,44 @@
 User Stories
 ============
 
-Agile principles:
+Reading list
+------------
+
+* [Mark Shead: Creating Good User Stories][Mark Shead]
+* [GOV.UK Service manual: Writing user stories][GOV.UK]
+* [Mike Cohn's blog posts about user stories][Mike Cohn]
+* [Mike Cohn: User Stories Applied (book)][User Stories Applied]
+* Splitting user stories (very important part):
+  * [Agile For All: Patterns for Splitting User Stories][Agile For All]
+  * [Lasse Koskela: Ways to Split User Stories][Koskela]
+  * [J.B. Rainsberger on splitting features][jbrains], also a long example in
+    [Three Steps to a Useful Minimal Feature][jbrains_example]
+
+[Mark Shead]: https://blogs.harvard.edu/markshead/good-user-stories/ "Mark Shead: Creating Good User Stories"
+[GOV.UK]: https://www.gov.uk/service-manual/agile-delivery/writing-user-stories "GOV.UK Service manual: Writing user stories"
+[Mike Cohn]: https://www.mountaingoatsoftware.com/blog/tag/user-stories "Mike Cohn's blog posts about user stories"
+[User Stories Applied]: https://www.amazon.com/gp/product/0321205685?ie=UTF8&tag=martinfowlerc-20&linkCode=as2&camp=1789&creative=9325&creativeASIN=0321205685 "Mike Cohn: User Stories Applied (book)"
+[Agile For All]: http://agileforall.com/patterns-for-splitting-user-stories/ "Agile For All: Patterns for Splitting User Stories"
+[Koskela]: https://web.archive.org/web/20120909082905/http://lassekoskela.com:80/thoughts/7/ways-to-split-user-stories/ "Lasse Koskela: Ways to Split User Stories"
+[jbrains]: https://web.archive.org/web/20120716060616/http://jbrains.ca/permalink/how-youll-probably-learn-to-split-features "J.B. Rainsberger on splitting features"
+[jbrains_example]: https://web.archive.org/web/20111231080154/http://www.jbrains.ca:80/permalink/three-steps-to-a-useful-minimal-feature "J.B. Rainsberger: Three Steps to a Useful Minimal Feature"
+
+
+User stories and agile
+----------------------
+
+Some Agile principles that user stories support (from [Mark Shead][]):
 
 * **Working software** is the primary measure of progress
+
 * #1 priority is satisfying **user needs** through early and continuous
-  delivery of valuable software
-* Keep it **simple** - maximize the amount of work _not_ done
+  delivery of valuable software.
+
+  Based on a Ron Jeffries _The Nature of Software Development_ I'd re-phrase
+  this as delivering **value**, where value is defined as "whatever you want".
+  Most of the time this should be user needs, but not always.
 
-- from [Mark Shead][].
+* Keep it **simple** - maximize the amount of work _not_ done
 
 More paraphrasing from Mark Shead:
 
@@ -23,21 +53,29 @@ The same goes for prioritising work with user stories. User stories are units
 that represent value to the customer. Working from user stories and delivering
 frequently minimizes project risk.
 
-GOV.UK have **every member of the team** writing user stories and using them
-to [track everything they need to do, think from a user's perspective,
-discuss work with colleagues, and prioritise work][GOV.UK]
-
+Who should write the user stories?
+----------------------------------
 
-Who writes user stories?
-------------------------
+Opinions differ. Some say it's best if the customers write them themselves
+(e.g. [User Stories Applied][]). [GOV.UK][] have every member of the team
+involved in writing user stories, which I think is a good idea because it gets
+everyone thinking from the user's point of view and gets everyone to understand
+what makes a good or a bad user story, gets the team communicating with
+each other in terms of user stories.
 
-Could be the product manager only, or could be anyone on the team, or could
-be the customer.
+I think it might be good if the product owner (or other non-dev people in the
+organization) write epics, and then developers split those into smaller
+stories.
 
-The customer or product owner prioritises them.
-
-Developers break them down into **tasks**.
+One it comes to splitting up stories into smallers ones, and certainly
+splitting small stories into dev tasks, developers need to take the lead
+because it involves a lot of developer knowledge and concerns.
 
+The customer, customer proxy or product owner should be the one who leads
+**prioritizing** the user stories, although dev input will be needed here on
+what sequence orders are possible or not and how / whether they affect cost.
+(And whoever wrote the stories should have tried to make them as independent
+from each other as possible so they can be prioritized as freely as possible.
 
 Basic contents of a good user story
 -----------------------------------
@@ -80,77 +118,56 @@ Good examples:
   (Example from [GOV.UK][].)
 
 * As a registered user I want to change my password so that I can keep my
-  account secure. (From [Mark Shead[].)
+  account secure. (From [Mark Shead][].)
 
 * As a website visitor I want to subscribe to the mailing list for a product so
-  I can get product updates through email. (From [Mark Shead[].)
+  I can get product updates through email. (From [Mark Shead][].)
 
   This seems wrong to me. Surely **As a website visitor I want to get product
   updates through email so that...** (what is the point of these product
   updates?)
 
 * As an admin user I want to disable a user so I can prevent unauthorized
-  logins by past employees. (From [Mark Shead[].)
+  logins by past employees. (From [Mark Shead][].)
 
   Same problem as above.
 
 * As a mobile app user I want to save all my data to the cloud so I can access
-  it from another device. (From [Mark Shead[].)
+  it from another device. (From [Mark Shead][].)
 
   Same problem as above.
 
-* As the HR manager, I want to create a screening quiz so that I can understand
-  whether I want to send possible recruits to the functional manager.
-
-* As a manager, I want to browse my existing quizzes so I can recall what I
-  have in place and figure out if I can just reuse or update an existing quiz
-  for the position I need now
-
-* As a user, I can indicate folders not to backup so that my backup drive isn't
-  filled up with things I don't need saved.
-
-  (Wikipedia)
-
+* A few from [Wikipedia](https://en.wikipedia.org/wiki/User_story#Examples):
 
-Bad examples:
+  * As the HR manager, I want to create a screening quiz so that I can understand
+    whether I want to send possible recruits to the functional manager.
 
-* As a developer I want a database with all the tables to model the data so I
-  store the information the application needs.
-
-  **It's a prerequisite for other user stories**. This is bad.  Almost all of
-  the application depends on this story being done first.
-
-  **It depends on other user stories**. This is bad. We can't know how to
-  implement this user story (how to design all the database tables) until we
-  know how we're going to build all the other parts of the system (that the
-  database tables will serve).
-
-  **Doesn't deliver user value**. We have no functionality we can show the user
-  when we've completed this story. The story isn't written from the user's
-  perspective.
-
-  Instead you should write a small user story from the user's perspective and
-  build **only the parts of the database that you need** (and only the parts of
-  every other layer that you need) to complete that small user story. A thin,
-  but top to bottom, slice.
-
-  This does means that code written for earlier user stories may need to be
-  rewritten when we get on to later user stories and realise things that we
-  didn't realise earlier. That's fine - the cost is trivial compared to the
-  benefits of delivering customer / user value sooner rather than later.
+  * As a manager, I want to browse my existing quizzes so I can recall what I
+    have in place and figure out if I can just reuse or update an existing quiz
+    for the position I need now
 
+  * As a user, I can indicate folders not to backup so that my backup drive isn't
+    filled up with things I don't need saved. (From Wikipedia)
 
 Properties that user stories should have
 ----------------------------------------
 
-1. Independent
+INVEST:
 
+1. Independent
+2. ...
 
 Adding detail to user stories
 -----------------------------
 
-Either by splitting them into smaller stories or by adding acceptance criteria.
+* Splitting them into smaller ones adds detail
+* Adding acceptance criteria, notes, tests, links to further reading
+* Just the right amount of detail
+* Detail just in time
+
+Reading:
 
+* <https://www.mountaingoatsoftware.com/blog/the-two-ways-to-add-detail-to-user-stories>
 
 Acceptance criteria
 -------------------
@@ -168,7 +185,7 @@ Acceptance criteria
 >   Thanksgiving to Christmas).
 > * Holiday seasons can be set to be a number of days prior to the holiday.
 >
-> - [Mike Cohn](https://www.mountaingoatsoftware.com/agile/user-stories)
+> -- [Mike Cohn][]
 
 > As a user, I am required to enter a strong password when creating my account.
 >
@@ -180,7 +197,7 @@ Acceptance criteria
 > * Must contain at least 1 lowercase letter
 > * Must contain at least 1 symbol
 >
-> - [Mike Cohn](https://www.mountaingoatsoftware.com/blog/the-two-ways-to-add-detail-to-user-stories)
+> -- [Mike Cohn](https://www.mountaingoatsoftware.com/blog/the-two-ways-to-add-detail-to-user-stories)
 
 Acceptance criteria add detail to a user story.
 
@@ -193,7 +210,8 @@ into separate stories so they can be prioritized separately.
 Splitting up user stories into smaller ones
 -------------------------------------------
 
-**Developers** need to split up user stories.
+I think **developers** need to split up user stories, because it requires
+developer knowledge and involves developer concerns.
 
 The product owner won't be able to split up user stories on her own in a way
 that's useful for developers. Product owner doesn't know how much work each
@@ -207,7 +225,7 @@ throw away** one of the new stories.
 
 An epic:
 
-> As a user, I can backup my entire hard drive. (An epic)
+> As a user, I can backup my entire hard drive.
 
 _Some_ of the smaller stories this would split into:
 
@@ -217,7 +235,7 @@ _Some_ of the smaller stories this would split into:
   filled up with things I don't need saved.
 * ...
 
-(Example from [Mike Cohn](https://www.mountaingoatsoftware.com/agile/user-stories))
+(Example from [Mike Cohn][])
 
 [Another example from Mike Cohn](https://www.mountaingoatsoftware.com/blog/the-two-ways-to-add-detail-to-user-stories):
 
@@ -247,7 +265,7 @@ much uncertainty** about a story.
 
 "Spike" label on GitHub issues.
 
-<http://agileforall.com/patterns-for-splitting-user-stories/> gives nine patterns:
+[Agile For All][] gives nine patterns:
 
 1. Workflow steps
 
@@ -318,7 +336,7 @@ much uncertainty** about a story.
    > …in Arabic.
    > …etc.
 
-   Another example from [Lasse Koskela](https://web.archive.org/web/20120909082905/http://lassekoskela.com:80/thoughts/7/ways-to-split-user-stories/):
+   Another example from [Lasse Koskela][Koskela]:
 
    > As a user looking for camera accessories I want to search for products so
    > that I can avoid browsing through the whole product catalog.
@@ -348,7 +366,7 @@ much uncertainty** about a story.
    > …using simple date input.
    > …with a fancy calendar UI.
 
-   Example from [Lasse Koskela](https://web.archive.org/web/20120909082905/http://lassekoskela.com:80/thoughts/7/ways-to-split-user-stories/):
+   Example from [Lasse Koskela][Koskela]:
 
    > As a beginning photographer I want to get recommended a camera kit to buy
    > so that I don’t need to spend hours reading reviews to figure out which
@@ -391,7 +409,7 @@ much uncertainty** about a story.
    > …I can edit my account settings.
    > …I can cancel my account.
 
-   Another example from [Lasse Koskela](https://web.archive.org/web/20120909082905/http://lassekoskela.com:80/thoughts/7/ways-to-split-user-stories/):
+   Another example from [Lasse Koskela][Koskela]:
 
    > As a shop keeper I want to manage the products being sold in my online
    > store so that I can sell what people want to buy.
@@ -414,7 +432,7 @@ much uncertainty** about a story.
 
 10. Splitting by role
 
-    Additional way of splitting from [Lasse Koskela](https://web.archive.org/web/20120909082905/http://lassekoskela.com:80/thoughts/7/ways-to-split-user-stories/):
+    Additional way of splitting from [Lasse Koskela][Koskela]:
 
     The initial user story involves two distinct users. Split into stories for
     each user:
@@ -441,18 +459,14 @@ much uncertainty** about a story.
     bullet! Or split where "and", "or", periods or other separators appear
     in the story.
 
-Another example of splitting stories from [J.B. Rainsberger](https://web.archive.org/web/20120716060616/http://jbrains.ca/permalink/how-youll-probably-learn-to-split-features):
+Another example of splitting stories from [J.B. Rainsberger][jbrains]:
 
 > "Collect registrations" splits into:
 >
 > * register with just e-mail, then pay with paypal.com
 > * collect more information from registrant (name, address, phone)
 > * notify both registrant and organizer after registration
 
-
-
-
-
 Splitting anti patterns
 -----------------------
 
@@ -476,12 +490,37 @@ Splitting anti patterns
   >
   > ...
 
-  (Example from [Lasse Koskela](https://web.archive.org/web/20120909082905/http://lassekoskela.com:80/thoughts/7/ways-to-split-user-stories/).)
+  (Example from [Lasse Koskela][Koskela].)
 
 
 User story anti patterns
 ------------------------
 
+* As a developer I want a database with all the tables to model the data so I
+  store the information the application needs.
+
+  **It's a prerequisite for other user stories**. This is bad.  Almost all of
+  the application depends on this story being done first.
+
+  **It depends on other user stories**. This is bad. We can't know how to
+  implement this user story (how to design all the database tables) until we
+  know how we're going to build all the other parts of the system (that the
+  database tables will serve).
+
+  **Doesn't deliver user value**. We have no functionality we can show the user
+  when we've completed this story. The story isn't written from the user's
+  perspective.
+
+  Instead you should write a small user story from the user's perspective and
+  build **only the parts of the database that you need** (and only the parts of
+  every other layer that you need) to complete that small user story. A thin,
+  but top to bottom, slice.
+
+  This does means that code written for earlier user stories may need to be
+  rewritten when we get on to later user stories and realise things that we
+  didn't realise earlier. That's fine - the cost is trivial compared to the
+  benefits of delivering customer / user value sooner rather than later.
+
 1. Circular
 
 2. Describing a solution not a problem.
@@ -594,6 +633,9 @@ Users in user stories
 
 <https://www.mountaingoatsoftware.com/blog/adding-decorated-user-roles-to-your-user-stories>
 
+Don't just say "**As a user**" all the time, refer to specific types and
+sub-types of users:
+
 1. Site visitor
 2. Former member (more specific type of site visitor)
 3. Registered member
@@ -612,22 +654,42 @@ The others are **decorated user roles**. Maybe important but not really an entir
 separate type of user.
 
 
-Epics
------
+Themes, epics, stories and tasks
+--------------------------------
 
-An epic is just a big user story. Too big to implement directly. They tend to
-come before the smaller user stories (it's easier to write the epics first).
-Can end up being split up into dozens or hundreds of user stories.
+You don't need a complex hierarchy or taxonomy of different types of story,
+just a few. A **theme** contains many epics and stories. A given sprint or
+sequence of sprints should have a single theme as its focus or top priority.
+An **epic** is a big user story that gets split into multiple stories at some
+point. **Stories**, once they're split up small enough, are the things you
+actually take into sprints. A story needs to be broken down into multiple
+within-sprint **tasks** (e.g. write the backend, write the frontend) in order
+to do it:
 
-"Epic" should ge a GitHub label. Don't think there's a good way to track what
-user stories belong to each epic, that isn't error prone.
+```
+Theme -(many)-> Epic -(many)-> Story -(many)-> Task
+```
 
+This isn't a strict hierarchy, though, they're more like labels: you could have
+an epic that stands on its own, doesn't belong to a theme. You could have a
+story that doesn't come from an epic. You could have a task that isn't part of
+a wider story (e.g.  tasks like "reboot the server"). So GitHub labels should
+work well for these.
+
+**Spike** is another example of a potential GitHub label. A spike is a type of
+story.
 
 Themes
 ------
 
-A theme is a collection of user stories. ("Theme:*" labels on GitHub.)
+A theme is a collection of user stories and epics.
 
+Epics
+-----
+
+An epic is just a big user story. Too big to implement directly. They tend to
+come before the smaller user stories (it's easier to write the epics first).
+Can end up being split up into dozens or hundreds of user stories.
 
 Tasks
 -----
@@ -642,11 +704,3 @@ Restricted to a single type of work (programming, testing, UI design, analysis,
 
 What developers break user stories down into. Task list on GitHub issue.
 "Task" GitHub label for standalone tasks.
-
-
-References
-----------
-
-* <https://www.mountaingoatsoftware.com/blog/advantages-of-the-as-a-user-i-want-user-story-template>
-* [GOV.UK]: https://www.gov.uk/service-manual/agile-delivery/writing-user-stories
-* [Mark Shead]: https://blogs.harvard.edu/markshead/good-user-stories/
diff --git a/user_stories.md b/user_stories.md
@@ -201,7 +201,9 @@ user story she creates implies so she can't make them equal sized. Product
 owner can't know about dependencies between user stories.
 
 **Different stories might have different priorities**, is another reason for
-splitting them up.
+splitting them up. Most of the value for a story usually comes from a small
+part of the functionality - splitting might even let you **deprioritize or
+throw away** one of the new stories.
 
 An epic:
 
@@ -245,6 +247,210 @@ much uncertainty** about a story.
 
 "Spike" label on GitHub issues.
 
+<http://agileforall.com/patterns-for-splitting-user-stories/> gives nine patterns:
+
+1. Workflow steps
+
+   Build the simple end-end case, or the most common case, first and then the
+   moddle steps and special cases.
+
+   > As a content manager, I can publish a news story to the corporate website.
+   >
+   > …I can publish a news story directly to the corporate website.
+   > …I can publish a news story with editor review.
+   > …I can publish a news story with legal review.
+   > …I can view a news story on a staging site.
+   > …I can publish a news story from the staging site to production.
+
+2. Business rule variations
+
+   > As a user, I can search for flights with flexible dates.
+   >
+   > …as “n days between x and y.”
+   > …as “a weekend in December.”
+   > …as “± n days of x and y.”
+
+3. Major effort
+
+   > As a user, I can pay for my flight with VISA, MasterCard, Diners Club, or
+   > American Express.
+   >
+   > …I can pay with one credit card type (of VISA, MC, DC, AMEX).
+   > …I can pay with all four credit card types (VISA, MC, DC, AMEX) (given one card type already implemented).
+
+   Most of the effort will go into implementing the first story.
+
+   The second new story depends on the first, but at least the dependency is clear.
+
+   Also, writing the user stories in this style defers the decision about
+   what order the four credit card types will be implemented in (including
+   which first), allowing those to be reprioritized freely.
+
+4. Simple / complex
+
+   Capture the simplest version of something as its own story. Use acceptance
+   criteria to keep it simple. Then break each variation and complexity into
+   its own story.
+
+   > As a user, I can search for flights between two destinations.
+   >
+   > …specifying a max number of stops.
+   > …including nearby airports.
+   > …using flexible dates.
+   > …etc.
+
+5. Variations in data / details
+
+   Separate stories for separate variations in data.
+
+   > As a user, I can search for transportation providers by trip origin and destination.
+   >
+   > As a user, I can search for transportation providers by trip origin and destination as counties.
+   >
+   > As a user, I can search for transportation providers by trip origin and destination as counties, cities, towns, or neighborhoods.
+   >
+   > Providers can serve different geographic areas for trip origin and destination.
+
+   > As a content manager, I can create news stories.
+   >
+   > …in English.
+   > …in Japanese.
+   > …in Arabic.
+   > …etc.
+
+   Another example from [Lasse Koskela](https://web.archive.org/web/20120909082905/http://lassekoskela.com:80/thoughts/7/ways-to-split-user-stories/):
+
+   > As a user looking for camera accessories I want to search for products so
+   > that I can avoid browsing through the whole product catalog.
+   >
+   > Splits into subsets of that fully featured search functionality:
+   >
+   > * As a user looking for camera accessories I want to search for products
+   >   by their name and description so that I can avoid browsing through the
+   >   whole product catalog.
+   >
+   > * As a user looking for camera accessories I want to search for products
+   >   by their price and availability so that I can avoid browsing through
+   >   items I wouldn’t buy anyway.
+
+   If the difference between supporting 2 or 4 data fields is negligible then
+   splitting this way doesn't make any sense.
+
+6. Data entry methods, a.k.a. splitting by quality or by utility vs usability.
+
+   When complexity is in the UI not the functionality itself.
+
+   Separate stories to build the simplest possible UI and then to build better
+   UIs. (The second story will depend on the first.)
+
+   > As a user, I can search for flights between two destinations.
+   >
+   > …using simple date input.
+   > …with a fancy calendar UI.
+
+   Example from [Lasse Koskela](https://web.archive.org/web/20120909082905/http://lassekoskela.com:80/thoughts/7/ways-to-split-user-stories/):
+
+   > As a beginning photographer I want to get recommended a camera kit to buy
+   > so that I don’t need to spend hours reading reviews to figure out which
+   > camera would suit me well.
+   >
+   > Splits into:
+   >
+   > As a beginning photographer I want to see a numeric sales rank so that I
+   > can better decide which camera to buy by comparing the sales of my
+   > alternatives.
+   >
+   > As a beginning photographer I want to see a numeric sales rank grouped by
+   > buyer expertise level so that I can better decide which camera to buy by
+   > comparing the sales of my alternatives.
+   >
+   > ...
+
+   These are things that deliver value (helping the user make the buying
+   decision), just not as much value as the original feature request for a
+   clear recommendation.
+
+7. Defer performance
+
+   When a large part of the effort is making it fast. But you can still learn
+   from the slow version, and it still has some value to the user who can now
+   undertake the action albeit slowly.
+
+   > As a user, I can search for flights between two destinations.
+   >
+   > …(slow—just get it done, show a “searching” animation).
+   > …(in under 5 seconds).
+
+8. CRUD operations
+
+   The word "manage" always contains multiple actions:
+
+   > As a user, I can manage my account.
+   >
+   > …I can sign up for an account.
+   > …I can edit my account settings.
+   > …I can cancel my account.
+
+   Another example from [Lasse Koskela](https://web.archive.org/web/20120909082905/http://lassekoskela.com:80/thoughts/7/ways-to-split-user-stories/):
+
+   > As a shop keeper I want to manage the products being sold in my online
+   > store so that I can sell what people want to buy.
+   >
+   > Splits into:
+   >
+   > As a shop keeper I want to add and remove products from my online store so
+   > that I can sell what people want to buy. (Editing can be done by deleting
+   > and re-adding.)
+   >
+   > As a shop keeper I want to edit product details in my online store so that
+   > I can avoid recreating a product to fix a typo etc. (If the first user
+   > story isn't done yet then adding new products must be done with raw
+   > SQL.)
+
+9. Break out a time-boxed spike
+
+   If the story is too large and poorly understood do a spike to resolve
+   uncertainty. After the spike either do the story or break the story up.
+
+10. Splitting by role
+
+    Additional way of splitting from [Lasse Koskela](https://web.archive.org/web/20120909082905/http://lassekoskela.com:80/thoughts/7/ways-to-split-user-stories/):
+
+    The initial user story involves two distinct users. Split into stories for
+    each user:
+
+    > Error handling.
+    > user friendly error messages
+    > detailed stack trace in log file
+    > unique error code displayed to user and in log file
+    >
+    > Splits into:
+    >
+    > As a user I want to see an error message I can understand when something
+    > goes wrong.
+    >
+    > As a programmer I want to see the full stack trace in the log file for
+    > any exception thrown during runtime so that I can better debug error
+    > situations.
+    >
+    > As a programmer I want to show the user a unique error situation
+    > identifier so that I can locate the relevant portion of the log file
+    > faster and more reliably.
+
+11. Split user stories that are bullet lists into separate stories for each
+    bullet! Or split where "and", "or", periods or other separators appear
+    in the story.
+
+Another example of splitting stories from [J.B. Rainsberger](https://web.archive.org/web/20120716060616/http://jbrains.ca/permalink/how-youll-probably-learn-to-split-features):
+
+> "Collect registrations" splits into:
+>
+> * register with just e-mail, then pay with paypal.com
+> * collect more information from registrant (name, address, phone)
+> * notify both registrant and organizer after registration
+
+
+
 
 
 Splitting anti patterns
@@ -257,6 +463,21 @@ Splitting anti patterns
   **A story should go through the entire stack**, or as much as the feature
   needs.
 
+  You can split along technical lines only if you can't think of any other way.
+  Example:
+
+  > As a potential buyer I want to see available multi-item discounts involving
+  > the product I’m currently looking at.
+
+  Splits into:
+
+  > As a product owner I want the discount subsystem to support multi-item
+  > campaigns so that I can deliver value to the user in a later iteration.
+  >
+  > ...
+
+  (Example from [Lasse Koskela](https://web.archive.org/web/20120909082905/http://lassekoskela.com:80/thoughts/7/ways-to-split-user-stories/).)
+
 
 User story anti patterns
 ------------------------

diff --git a/user_stories.md b/user_stories.md
@@ -0,0 +1,431 @@
+User Stories
+============
+
+Agile principles:
+
+* **Working software** is the primary measure of progress
+* #1 priority is satisfying **user needs** through early and continuous
+  delivery of valuable software
+* Keep it **simple** - maximize the amount of work _not_ done
+
+- from [Mark Shead][].
+
+More paraphrasing from Mark Shead:
+
+Software projects fail because they aren't focused on delivering actual value
+to the user regularly.
+
+A software increment that completes a user story is a valuable software
+increment in terms of user needs. A delivered user story gives the user the
+ability to do something valuable with the software. So tracking work with user
+stories is a way to measure progress in terms of value (user needs) delivered.
+The same goes for prioritising work with user stories. User stories are units
+that represent value to the customer. Working from user stories and delivering
+frequently minimizes project risk.
+
+GOV.UK have **every member of the team** writing user stories and using them
+to [track everything they need to do, think from a user's perspective,
+discuss work with colleagues, and prioritise work][GOV.UK]
+
+
+Who writes user stories?
+------------------------
+
+Could be the product manager only, or could be anyone on the team, or could
+be the customer.
+
+The customer or product owner prioritises them.
+
+Developers break them down into **tasks**.
+
+
+Basic contents of a good user story
+-----------------------------------
+
+You should do as much as you can to **increase the quality of your user
+stories**. This will pay dividends by making subsequent development more
+efficient. The user stories are the foundation on which a lot of time is going
+to be spent planning and developing, so get them right.
+
+1. Who the user is (**As a...**)
+
+2. What the user needs (**I need/want/expect to...**).
+
+   This (the goal) is the most important part because it's how you know that
+   the thing you're building solves the right problem, and how you decide when
+   a story is done (possibly with help from acceptance criteria).
+
+3. Why they need it (**So that...**). Some people consider this part optional.
+
+4. Optional acceptance criteria (**It's done when...**), a checklist of
+   outcomes that can be used to confirm when a story is done.
+
+   You can also **link to any supporting evidence** in acceptance criteria.
+
+2, 3 and 4 together must describe **what the world must look like in order to
+mark this user story as complete**.
+
+Good examples:
+
+* As a UK resident, I want to get my details on the electoral register so that
+  I can vote.
+
+  Acceptance criteria:
+
+  - [ ] It's done when the user knows how to register online
+  - [ ] It's done when the user knows how to download a form to register by
+        post
+  - [ ] It's done when the user knows where to send the form
+
+  (Example from [GOV.UK][].)
+
+* As a registered user I want to change my password so that I can keep my
+  account secure. (From [Mark Shead[].)
+
+* As a website visitor I want to subscribe to the mailing list for a product so
+  I can get product updates through email. (From [Mark Shead[].)
+
+  This seems wrong to me. Surely **As a website visitor I want to get product
+  updates through email so that...** (what is the point of these product
+  updates?)
+
+* As an admin user I want to disable a user so I can prevent unauthorized
+  logins by past employees. (From [Mark Shead[].)
+
+  Same problem as above.
+
+* As a mobile app user I want to save all my data to the cloud so I can access
+  it from another device. (From [Mark Shead[].)
+
+  Same problem as above.
+
+* As the HR manager, I want to create a screening quiz so that I can understand
+  whether I want to send possible recruits to the functional manager.
+
+* As a manager, I want to browse my existing quizzes so I can recall what I
+  have in place and figure out if I can just reuse or update an existing quiz
+  for the position I need now
+
+* As a user, I can indicate folders not to backup so that my backup drive isn't
+  filled up with things I don't need saved.
+
+  (Wikipedia)
+
+
+Bad examples:
+
+* As a developer I want a database with all the tables to model the data so I
+  store the information the application needs.
+
+  **It's a prerequisite for other user stories**. This is bad.  Almost all of
+  the application depends on this story being done first.
+
+  **It depends on other user stories**. This is bad. We can't know how to
+  implement this user story (how to design all the database tables) until we
+  know how we're going to build all the other parts of the system (that the
+  database tables will serve).
+
+  **Doesn't deliver user value**. We have no functionality we can show the user
+  when we've completed this story. The story isn't written from the user's
+  perspective.
+
+  Instead you should write a small user story from the user's perspective and
+  build **only the parts of the database that you need** (and only the parts of
+  every other layer that you need) to complete that small user story. A thin,
+  but top to bottom, slice.
+
+  This does means that code written for earlier user stories may need to be
+  rewritten when we get on to later user stories and realise things that we
+  didn't realise earlier. That's fine - the cost is trivial compared to the
+  benefits of delivering customer / user value sooner rather than later.
+
+
+Properties that user stories should have
+----------------------------------------
+
+1. Independent
+
+
+Adding detail to user stories
+-----------------------------
+
+Either by splitting them into smaller stories or by adding acceptance criteria.
+
+
+Acceptance criteria
+-------------------
+
+> As a vice president of marketing, I want to select a holiday season to be
+> used when reviewing the performance of past advertising campaigns so that I
+> can identify profitable ones.
+>
+> Acceptance criteria:
+>
+> * Make sure it works with major retail holidays: Christmas, Easter,
+>   President’s Day, Mother’s Day, Father’s Day, Labor Day, New Year’s Day.
+> * Support holidays that span two calendar years (none span three).
+> * Holiday seasons can be set from one holiday to the next (such as
+>   Thanksgiving to Christmas).
+> * Holiday seasons can be set to be a number of days prior to the holiday.
+>
+> - [Mike Cohn](https://www.mountaingoatsoftware.com/agile/user-stories)
+
+> As a user, I am required to enter a strong password when creating my account.
+>
+> Acceptance criteria:
+>
+> * Must have at least 8 characters
+> * Must contain at least 1 digit
+> * Must contain at least 1 uppercase letter
+> * Must contain at least 1 lowercase letter
+> * Must contain at least 1 symbol
+>
+> - [Mike Cohn](https://www.mountaingoatsoftware.com/blog/the-two-ways-to-add-detail-to-user-stories)
+
+Acceptance criteria add detail to a user story.
+
+Acceptance criteria shouldn't make a story too big for one sprint (in that case
+split it into multiple stories).
+
+Acceptance criteria should be of **equal priority**, if they aren't then split
+into separate stories so they can be prioritized separately.
+
+Splitting up user stories into smaller ones
+-------------------------------------------
+
+**Developers** need to split up user stories.
+
+The product owner won't be able to split up user stories on her own in a way
+that's useful for developers. Product owner doesn't know how much work each
+user story she creates implies so she can't make them equal sized. Product
+owner can't know about dependencies between user stories.
+
+**Different stories might have different priorities**, is another reason for
+splitting them up.
+
+An epic:
+
+> As a user, I can backup my entire hard drive. (An epic)
+
+_Some_ of the smaller stories this would split into:
+
+* As a power user, I can specify files or folders to backup based on file size,
+  date created and date modified.
+* As a user, I can indicate folders not to backup so that my backup drive isn't
+  filled up with things I don't need saved.
+* ...
+
+(Example from [Mike Cohn](https://www.mountaingoatsoftware.com/agile/user-stories))
+
+[Another example from Mike Cohn](https://www.mountaingoatsoftware.com/blog/the-two-ways-to-add-detail-to-user-stories):
+
+> As a user, I can log in through a social media account.
+
+Splits into:
+
+* As a user, I can log in through my Facebook account.
+* As a user, I can log in through my LinkedIn account.
+* As a user, I can log in through my Twitter account.
+
+### Splitting based on paths through the story
+
+What paths can the user take in performing the story? For example showing
+overnight, two-day, or slow delivery. Split into story 1: slow delivery (no
+choice) (and then presumably add two-day then add overnight).
+
+
+### Extracting a spike from a story
+
+Extract a "Spike to investigate..." card out of the user story card.
+Reduce risk and uncertainty, learn more about unfamiliar technologies.
+And **discover new ways to better split the story**.
+
+Don't split a spike out of _every_ story though. Use them **when there's too
+much uncertainty** about a story.
+
+"Spike" label on GitHub issues.
+
+
+
+Splitting anti patterns
+-----------------------
+
+* Unbalanced. 99% of the work is in one story.
+
+* Splitting along technical boundaries (backend, frontend, etc).
+  Results in stories that give no user value.
+  **A story should go through the entire stack**, or as much as the feature
+  needs.
+
+
+User story anti patterns
+------------------------
+
+1. Circular
+
+2. Describing a solution not a problem.
+
+3. Jumping right into how:
+
+   > As a participant who has just finished a course, I'd like a **more
+   > prominent call to action** asking me for a review.
+
+   Instead start with the **goal** (to get more reviews). This user story has
+   already decided that a more prominent call to action is _how_ to get more
+   reviews.
+
+   Just adding a "so that" (and leaving the prominent call to action in) is
+   already an improvement:
+
+   > As a participant who has just finished a course, I'd like a more prominent
+   > call to action asking me for a review, **so that there are more reviews on
+   > the site**.
+
+   But this still isn't right though (it's not the participant who wants more
+   reviews, it's the course owner).
+
+   (Example from [Mike Cohn](https://www.mountaingoatsoftware.com/blog/critiquing-one-of-my-own-real-user-stories).)
+
+4. Wrong user.
+
+   > As Front Row Agile, I want participants to be encouraged to review a
+   > course after finishing the course, so we can have more feedback about how
+   > folks like our courses.
+
+3. Too much detail. Not everything needs to be known before starting a story.
+
+   Too much time spent on writing user stories. Takes longer to get feedback
+   from users and stakeholders as time is spent adding detail to stories before
+   actually delivering working code.
+
+   Loss of creativity, programmers are just doing exactly what they're told.
+
+   Details that are added too long before the details will likely not be right
+   anymore by the time the user story gets worked on.
+
+   Implementation details start to creep in to the stories.
+
+4. Too little detail.
+
+   Story is too hard to implement as time is spent seeking answers to
+   unanswered questions, and/or development goes astray by filling in the gaps
+   with the wrong things.
+
+5. User stories that are prerequisites for and / or depend on other user
+   stories.
+
+6. Too big to implement directly (it's an epic, it needs to be split up).
+   Needs to be small enough to deliver in a single sprint.
+
+7. Specifying the solution as part of the user story.
+
+   User stories should focus on **what** needs to be done, not **how** it'll
+   be done.
+
+8. [User stories as mini specification documents, and doing iterative waterfall instead of agile](https://www.mountaingoatsoftware.com/blog/an-iterative-waterfall-isnt-agile).
+
+   <blockquote>I've noticed something disturbing over the past two years. And
+   it's occurred uniformly with teams I've worked with all across the world.
+   It's the tendency to create an iterative waterfall process and then to call
+   it agile.</blockquote>
+
+   Doing lots of Analysis -> Design -> Coding -> Testing mini waterfalls (one
+   per user story) isn't agile, it's iterative waterfall.
+
+   In agile analysis, design, coding and testing start and finish at the same
+   time. They overlap as much as possible, and upfront analysis, design etc are
+   done as late as possible.
+
+   Don't treat user stories as mini specification documents.
+
+   Treat a user story as a promise to have a conversation.
+
+   Optionally, add notes to some user stories about things to make sure to
+   bring up during that conversation.
+
+9. [Not everything needs to be a user story](https://www.mountaingoatsoftware.com/blog/not-everything-needs-to-be-a-user-story-using-fdd-features).
+
+   More technical, less user-facing tasks (APIs, system capabilities, ...) can
+   instead be writting using Feature Driven Development (FDD) features in the
+   format:
+
+   ```
+   <action (verb)> the <result> <by|for|of|to> <object>
+   ```
+
+   Examples:
+
+   * Estimate the closing price of stock
+   * Generate a unique identifier for a transaction
+   * Change the text displayed on a kiosk
+   * Merge the data for duplicate transactions
+
+* [Having a complicated story hierarchy or taxonomy](https://www.mountaingoatsoftware.com/blog/you-dont-need-a-complicated-story-hierarchy) (feature -> saga -> epic -> novel -> story -> headline)
+
+  Themes (groups of user stories), epics (big user stories that need to be
+  split up), user stories and tasks will do.
+
+10. [Too long](https://www.mountaingoatsoftware.com/blog/names-should-not-be-needed-for-user-stories).
+
+
+Users in user stories
+---------------------
+
+<https://www.mountaingoatsoftware.com/blog/adding-decorated-user-roles-to-your-user-stories>
+
+1. Site visitor
+2. Former member (more specific type of site visitor)
+3. Registered member
+4. Known visitor
+5. Unknown visitor
+6. Premium member
+7. Trial member
+8. First-time visitor (add an adjective)
+9. First-time member
+10. Forgetful member
+
+The first 7 are **first class users**, significant to the success of the system
+and will appear often in user stories.
+
+The others are **decorated user roles**. Maybe important but not really an entirely
+separate type of user.
+
+
+Epics
+-----
+
+An epic is just a big user story. Too big to implement directly. They tend to
+come before the smaller user stories (it's easier to write the epics first).
+Can end up being split up into dozens or hundreds of user stories.
+
+"Epic" should ge a GitHub label. Don't think there's a good way to track what
+user stories belong to each epic, that isn't error prone.
+
+
+Themes
+------
+
+A theme is a collection of user stories. ("Theme:*" labels on GitHub.)
+
+
+Tasks
+-----
+
+Code this, design that, create test data for such-and-such, automate that,
+have a design review meeting.
+
+Usually things done by one person.
+
+Restricted to a single type of work (programming, testing, UI design, analysis,
+...).
+
+What developers break user stories down into. Task list on GitHub issue.
+"Task" GitHub label for standalone tasks.
+
+
+References
+----------
+
+* <https://www.mountaingoatsoftware.com/blog/advantages-of-the-as-a-user-i-want-user-story-template>
+* [GOV.UK]: https://www.gov.uk/service-manual/agile-delivery/writing-user-stories
+* [Mark Shead]: https://blogs.harvard.edu/markshead/good-user-stories/
No results found