Some User-Story Examples

Kindle screensaver asking for feedbackI’m often asked if I have any good user-story examples to share. Until recently, I always had to answer, “No,” because I didn’t have permission from my clients to share their work product. Then, the other day, it occurred to me that I could kill two birds with one stone. As an avid user of Amazon’s Kindle e-reader, I had some feedback to share with Amazon — feedback that I hope might improve the already excellent product. I decided to write up my feedback in the form of user-stories, complete with acceptance criteria. Below, therefore, you will find four new-feature stories and one bug-report story, each with three or four acceptance-test scenarios.

I did this partially just as a mental exercise, but I also reasoned that the more fully-fleshed out my feedback appeared, the more usable it might be to the Amazon developers, and the more likely my feedback might be acted upon. Anyway, even if they only turn out to be good learning examples, I’m happy.

I tried hard to make these stories self-explanatory, even for those of you who are not Kindle users. But, don’t hesitate to ask me for clarifications, if needed. I can post some photos, or other illustrations. The important things to notice are:

  • that the business value of the stories, and each of their scenarios, is clear,
  • how the information is presented in ever-deepening levels of abstraction, starting with the “In order to” clause which gives the overall motivation. followed by the “I want” clause which actually names the request, followed by the supporting scenarios which give concrete examples,
  • that the scenarios “lock down” all variables that may be important, or conversely, may be confusing if left out, and
  • in general, that the stories follow the INVEST mnemonic (Independent, Negotiable, Valuable, Estimable, Small, and Testable)

[The introduction above, like the rest of this blog, is © Craig L. Jones, 2011. However, the user story examples below are hereby released into the public domain, per Craig L. Jones, 14-July-2011.]

Feature: Consistent Use of Larger Font

In order to fully support customers with less than 20/20 vision (e.g. anyone over 40 years old)

As a far-sighted user who appreciates being able to increase the font size rather than having to switch to reading glasses

I want the increased font size to work throughout the reading app, including dialog boxes and error messages — not just for displaying the e-book text itself

Scenario: Larger Font when Entering New Notes

Given the Kindle is in reading mode for a normal e-book

And the current font-size setting is >=5 (of eight)

And the current font-typeface setting is regular

And the current line-spacing setting is small

And the current words-per-line setting is default

When I enter a note

Then the font-size characteristic for the note itself should be the same as the e-book text

And the button labels (‘cancel’, ‘clear’, ‘save & share’, and ‘save note’) should also be correspondingly larger

Scenario: Larger Font when Displaying Existing Notes

Given the Kindle is in the mode for displaying my highlights and notes

And the current font-size setting is >=5 (of eight)

And the current font-typeface setting is regular

And the current line-spacing setting is small

And the current words-per-line setting is default

When I scroll to an entry with a note

Then the font-size characteristic for the note itself should be the same as the corresponding e-book passage text

And the button labels (‘delete’, ‘share’, and ‘edit’) should also be correspondingly larger

Scenario: Larger Font when Displaying Error Messages

Given the Kindle is in reading mode for an e-book free sample (in which highlighting is disabled)

And the current font-size setting is >=5 (of eight)

And the current font-typeface setting is regular

And the current line-spacing setting is small

And the current words-per-line setting is default

When I attempt to highlight a passage and an error message is displayed saying “Annotating is disabled for sample content”

Then the font-size characteristic for the error message should be the same as the e-book text

Scenario: Larger Font when Displaying Dictionary Definitions

Given the Kindle is in reading mode for a normal e-book

And the current font-size setting is >=5 (of eight)

And the current font-typeface setting is regular

And the current line-spacing setting is small

And the current words-per-line setting is default

When I navigate to a word on the page and the definition for that word is displayed at either the top or bottom of the page

Then the font-size characteristic for the definition should be the same as the e-book text

And the button label for the ‘more’ button should also be correspondingly larger

Feature: Tagging Notes

In order to improve the usefulness of the Kindle system’s note-taking ability

As a studious reader who averages 75 highlights and/or notes per e-book

I want the ability to “tag” my highlights/notes with one- or two-word phrases of my choosing (e.g. ‘action item’, ‘vocabulary’, ‘key thought’, ‘errata’, or ‘obsolete’) and then work with my notes accordingly

Scenario: Create a new tag (for a new or existing note/highlight)

Given I have begun to enter a new note, Or I have begun to edit an existing note

And the new/existing note does not yet have a tag

When I navigate to the (new) tag field and begin to enter a word or phrase

Then whatever I type will be associated with that passage

And whatever I type will be added to the list of known tags

Scenario: Reuse an existing tag

Given I have begun to enter a new note, Or I have begun to edit an existing note

And the new/existing note does not yet have a tag

When I navigate to the (new) tag field and begin to enter a word or phrase

And there are one or more existing tags that begin with the same letters that I have typed so far

Then the first existing tag that matches is displayed in the tag field, with the letters that I have typed so far to the left of the cursor and the rest of the letters in the matching tag to the right of the cursor

And the matching tag is saved when I navigate away from the tag field

Scenario: Use a subset of an existing tag

Given I have begun to enter a new note, Or I have begun to edit an existing note

And the new/existing note does not yet have a tag

When I navigate to the (new) tag field and begin to enter a word or phrase

And there are one or more existing tags that begin with the same letters that I have typed so far

And I press the Return key

Then the tag will be truncated to just the letters that I have actually typed

And only that text will be saved as a tag

Feature: Filtering Notes by Tag (on Kindle)

In order to improve the usefulness of the Kindle system’s note-taking ability

As a studious reader who averages 75 highlights and/or notes per e-book

I want the ability to review my notes by filtering them according to the “tags” that I have assigned to them

Scenario: Filter by tag

Given I am reading an e-book on the Kindle

And I select ‘View Notes & Marks’

And I scroll to the left of “Showing All 75 Notes & Marks” and see not only the usual three filters for mark type (‘bookmark’, ‘note’, or ‘highlight’), but also one filter for every unique tag that I have attached to my notes for this e-book

When I select one of the tags

Then my list of notes and marks is filtered down to just the items that have that tag associated with it

Scenario: Filter by un-tagged

Given I am reading an e-book on the Kindle

And I select ‘View Notes & Marks’

And I scroll to the left of “Showing All 75 Notes & Marks” and see not only the usual three filters for mark type (‘bookmark’, ‘note’, or ‘highlight’), but also one filter for every unique tag that I have attached to my notes for this e-book, plus one more filter labeled “untagged”

When I select the “untagged” filter

Then my list of notes and marks is filtered down to just the items that do not have any tag associated with it (yet).

Feature: Sorting or Filtering Notes by Tag on PC (or Mac, iPad, etc.)

In order to improve the usefulness of the Kindle system’s note-taking ability

As a studious reader who averages 75 highlights and/or notes per e-book

I want the ability to review and manage my notes by sorting and/or filtering them according to the “tags” that I have assigned to them

Scenario: Filter by tag

Given I am reading an e-book using the Kindle app for PC

And I select ‘Show Notes & Marks’ from the View Menu

And I click on the filter choices combo-box

And I see not only the usual three filters for mark type (‘bookmark’, ‘note’, or ‘highlight’), but also one filter for every unique tag that I have attached to my notes for this e-book

When I select one of the tags

Then the list of notes and marks is filtered down to just the items that have that tag associated with it

Scenario: Sort by tag name

Given I am reading an e-book using the Kindle app for PC

And I select ‘Show Notes & Marks’ from the View Menu

And I click on the (new) sort-order choices combo-box

And I see two choices (‘by location’, or ‘by tag’)

When I select ‘by tag’

Then the list of notes and marks is sorted to show them in alphabetical order by tag name with a section header for every tag, followed by the note(s) that are associated with that tag (in location order)

And the end of the list contains one last section with a header labeled ‘untagged’ that shows all of the notes that do not have any tag, if any.

Scenario: Filter by un-tagged

Given I am reading an e-book using the Kindle app for PC

And I select ‘Show Notes & Marks’ from the View Menu

And I click on the filter choices combo-box

And I see not only the usual three filters for mark type (‘bookmark’, ‘note’, or ‘highlight’), but also one filter for every unique tag that I have attached to my notes for this e-book, plus one more filter labeled “untagged”

When I select the “untagged” filter

Then the list of notes and marks is filtered down to just the items that do not have any tag associated with it (yet).

Bug: Highlighting a Passage that Contains a Word-Wrapped Hyphen

In order for the Kindle to work as designed

As any Kindle user

I want the highlight feature to work properly when the passage I’m highlighting contains a hyphenated word and that word is wrapped at the hyphen.

Scenario: Hard Hyphen, Display of Highlighting In Progress

Given I am reading an e-book that allows passages to be highlighted (i.e. not a free sample, e.g “Anatomy of a Food Addiction” by Anne Katherine)

And I navigate to a section that contains a hyphenated word (e.g. location 1215/p. 62, “That’s different from self-indulgence.”)

And I adjust the font size upwards or downwards until the word-wrapping causes the hyphenated word to be split across two lines (e.g. “different from self-” followed by “indulgence. I’ve often heard”)

When I begin to highlight a passage that includes the hyphenated word, moving from left to right across the hyphenated word

Then the inverted characters (white on black) that track the highlighting in progress should move smoothly from the line with the first half of the hyphenated word (“different from self-“) to the next line (“indulgence. I’ve often heard”), and not jump immediately to the line after that (“women say, ‘I worked too”).

Scenario: Hard Hyphen, Display Existing Highlight

Given I am reading an e-book that allows passages to be highlighted (i.e. not a free sample, e.g “Anatomy of a Food Addiction” by Anne Katherine)

And I navigate to a section that contains a hyphenated word (e.g. location 1215/p. 62, “That’s different from self-indulgence.”)

And that section has an existing highlighted passage that includes that hyphenated word (“Whether we like the idea or not, to recover, we must learn self-kindness. That’s different from self-indulgence.”

When I adjust the font size upwards or downwards until the word-wrapping causes the hyphenated word to be split across two lines (e.g. “different from self-” followed by “indulgence. I’ve often heard”)

Then the text of the highlighted passage should remain consistently underlined. That is, the underlining of the last portion of the highlighted passage should not mysteriously jump to the line below where the highlighted passage ends.

Scenario: Soft Hyphen, …

(TBD — Are there corresponding soft-hyphen scenarios? If so, do they need to be spelled out explicitly?)