Thomas A. Alspaugh
Narrative Requirements

Under Construction


Why use narratives?

Why not narratives?

Narrative possibilities


A single point in time

A case of use

Perhaps the simplest requirements statement is that of a case of use of the desired system. A case of use states a situation in which the system could be used, if it existed. The situation is often one that exists in the pre-system world, so it is easy to visualize what the situation would be and to evaluate and discuss it.

A case of use doesn't describe the system, it describes the problem the system is projected to address. In some sense it is the seed of a story that hasn't been told yet.

A developer needs to schedule a meeting that includes someone higher up than he/she is. If the higher-up doesn't attend, the meeting is pointless.

So much energy is wasted when the lights are left on.

I need to get to the hospital in a hurry.

User Stories

A user story is a short statement of something desired; by custom, it is handwritten on a 3x5 card or a post-it. If it won't fit on a single card or post-it, then it's too long and is divided into two or more simpler statements.

The canonical form of a user story is

As a ROLE, I want DESIRE so that BENEFIT

but in practice the benefit is optional (As a ROLE, I want DESIRE), and in extreme cases so is the role (DESIRE).

Comparable Stories

As a developer, I want narrative requirements that can be automatically compared for equivalence, so that I don't have to read every one whenever I think I might need to add a new one.

Browser Self-Control

As a user, I want my browser to not open a pop-up or a new window, save Flash cookies, or send information about me, so that I feel like I'm in control of my browsing, not the sites I browse.

The use of a 3x5 or post-it produces an artifact that can be moved and grouped as the requirements on it are being conceptually moved and grouped. For example, the requirements being considered can be written on post-its and stuck up on the wall, then moved around as their requirements are moved up or down in priority, placed off to one side if they have been taken out of consideration, grouped together into planned releases, divided up by the person who will implement them, and so forth. In the scrum process, the user stories in the backlog are typically grouped together, in a stack of cards for example that is saved until the next sprint planning meeting, and the cards in the sprint tasks may be moved around as they go from planned to implemented to tested, or onto someone else's pile if a task is reassigned.

The use of a card or post-it also enforces the requirement that the user story be short. Some projects standardize on 4x6 cards so more information can be carried along with or in the story, but even the larger size card gives a hard limit to the length and amount of detail for one story.

Narrative Streams

Unstructured Text

Unstructured text is the basic narrative form. It is what people spontaneously produce, and have been producing for millennia.

Unstructured text narratives most strongly exhibit the advantages of narrative requirements. They produce the strongest intuitive reactions in their listeners of any of these narrative forms, and provoke the most thought. They can convey a great deal of information in a small space. People like them.

Example: Meeting Scheduler Automation scenario #2 (DIY)

Pointy-haired manager (PHM) decides to hold a meeting as soon as possible to discuss with Dilbert and Wally the assignment of cubicles.  He enters a meeting request into the Decide-it-Yourself (DIY) scheduler, stating the purpose of the meeting and that he wants to hold it by end of business tomorrow and that Dilbert, Wally and he need to be there.  DIY queries all three online calendars and finds free times 9-10am and 4-5pm.  It presents that list to PHM, who picks 4-5pm.  DIY queries the online calendars of rooms convenient for PHM, and finds two that are free at that time.  PHM picks the one with the view of the dumpsters.  DIY then composes a boilerplate e-mail message to Dilbert and Wally about the requested meeting, and reminds them to update their calendars accordingly. 

Colin Potts, Meeting scheduler automation scenarios, 2001

Audio and video

Audio and video recordings have many of the advantages of unstructured text. Video in particular can be even more effective in provoking thought and useful comment about a requirements narrative (Pang+Maiden+2005-drms).

However they also have some disadvantages. The primary one is their cost, which (especially for video) can be many times higher than other narrative forms. They are also more difficult to index and to skim, and require specialized tools in order for users to mark them up, by comparison to the other forms of narrative which can be printed. They are also more difficult to evolve as the narrative changes, and require specialized tools and skills from people working with them.

Narratives in Steps

Perhaps the simplest way of structuring a narrative is to break it into steps. Many (but not all) narratives can be considered as a sequence of events, such that everything in the narrative can be cleanly divided up into separate steps, with each thing clearly in exactly one step, and all the steps together adding up to the totality of the narrative. There are a number of different ways of doing this, some of which are described below.

However, note that not every narrative can be cleanly partitioned into separate events; and even if a narrative can be partitioned, many narratives have non-sequential relationships between some events, such as overlap, containment in time, synchronization, or just simply vagueness. In some forms of narrative-in-steps it is implicitly or explicitly assumed that each step takes place instantaneously, with no duration; this convenient abstraction does not match the physical world. While unstructured text handles these possibilities, although not always as well as we would like for requirements, a narrative divided into steps has thrown away this information completely, in some sense. It is common to see that the textual description constituting a step in a use case, for example, attempts to put back in some of the non-sequentialness or vagueness that the narrative-as-steps format has excluded.

The primary advantage of a narrative in steps, in my view, is that the step structure, if cleanly defined, can provide a formal basis on which useful automated support can be built. However, this has not been widely utilized.

A second advantage of a narrative in steps is that a step provides a useful unit of analysis and management for a group of such narratives, so that they can be worked with more easily than an equivalent set of unstructured text narratives.

Event Sequences

Kid pushes all the buttons

  1. A kid enters the elevator and sees that no one else is around.
  2. He/she pushes all the call buttons so they are all lit up.
  3. Before the doors close, he/she leaps back out.
  4. He/she walks off feeling satisfied.

EMS scenarios

Use Cases

Use cases are very widely used in software development, particularly in the U.S. (less so in other countries) (Cockburn2000-weuc). There are many formats for use cases; a representative one is illustrated by the use case below.

There are a number of standard, more-or-less well defined relationships between use cases:

In order to be satisfactory, a use case relationship should be defined clearly enough that a mechanical, preferably automated, process could produce the new use case that is specified by the relationship on the original use case or cases.

In practice, one sees these structures in addition to simple sequence of steps:

Here is a use case from a project in industry:

UC-02: Add / Edit / Clone / Delete Channel
Summary User creates, modifies, or deletes a channel.
Priority Essential
User Frequency Frequent
Direct Actors Mirth user
Main Success Scenario
1) User selects "Channels" page
2) System fetches and displays channel list
3) User selects between options (Add / Edit / Clone / Delete Channel)
4a) If delete, skip to last step
4b) System loads Channel Configuration page
5) User chooses a channel name, and selects endpoints, filters, and transformations, with a specific order
6) User submits selections
7) System updates Configuration Manager
Alternate Scenario Extension
5) User realizes he/she is missing a component and exits Channel Configuration page
6) System saves the entered information
7) User submits the components (other use cases) and returns to [sic]
8) User returns to Channel Configuration page
9) Sy[s]tem displays saved information
10) Process is at step 5 of MSS
Exception Scenario Extension
7) System updates Configuration Manager
8) Configuration Manager refuses the channel
9) System informs user of error

Problems with use cases

Use cases are associated with a number of problems specific to their form and definition:

  1. Alternatives are often misunderstood.  Almost use case we have seen that includes alternatives causes confusion (documented). The lack of a standard, well-defined means of stating a alternative means that authors and readers of use cases do not have the same understanding of them, unless the use case as written is clarified, typically by verbal discussions. A standard, well-defined notation should support a mechanical or automated process by which a person can obtain the sequence of events that is represented by a use case in which one specific alternative is taken. We have seen people infer several different interpretations of the same use case alternative, which means that use case is not a good form of requirements (or even just of communication).
  2. Inclusion is often misused and not thought through.  One use case including another at least appears to have a single widespread interpretation. However, it is typically used carelessly, despite the single interpretation. The most common problem is that the included use case does not match the context of the use case that includes it, so that a reader must make a guess about how the two contexts will be resolved. A second common problem, especially where inclusion is used two or more levels deep, is that most readers (and apparently most authors) do not take the trouble to chase down the included use case, especially ones two or levels down. Again, the result is a use case that is not good for requirements or even for communication.
  3. Readers don't read use cases carefully.  While the tabular format of a use case should be good as a means of organizing information, we have seen evidence that for some reason readers do not extract the information in them as effectively as they do from other formats presenting the same information.


A storyboard presents a narrative in a sequence of pictures, typically with some text for each picture. A comic book is one form of storyboard. Storyboards appear to offer some interesting advantages over text-only or rich media narrative forms, especially if they are drawn comic book style (Williams+Alspaugh2008-asrc):

  1. The pictures and the text cooperate to tell the story. The pictures and text may be redundant to a certain extent, in which case they reinforce each other and provide better understanding among people who may be of different backgrounds; or they may show different aspects of the story, in which case (for example) one can tell the main story, while another gives a second aspect of it, another point of view, a character's emotional state, a relationship to a memory or an envisioned future, and so forth.
  2. A storyboard can be sketchy, leaving out inessential detail or specifics not yet decided, and leaving more for the reader to imagine. A storyboard has the possibility of being appropriately vague.
  3. The iconic style of comic book characters invites readers to put themselves in a character's place, possibly inducing them to be more effectively engaged in what the storyboard is telling and thus explore their own goals and needs more effectively.
  4. The space between the panels demands that readers fill in what happens between, inviting them to make an imaginative leap to figure out what is missing. This may surface goals and concerns that would otherwise remain latent.
music comic

From Williams+Alspaugh2008-asrc (rights reserved).


Traditional animations are out of reach for the vast majority of development projects. However, we explored what can be done with automatically-produced social animations involving autonomous characters, driven by scenarios in a formal event-sequence language. (Alspaugh+Tomlinson+Baumer2006-usav) (movie). We found that the resulting presentation appeared to offer benefits in enabling non-experts to understand a system described by the animated scenarios.

autonomous animated characters

From Alspaugh+Tomlinson+Baumer2006-usav (rights reserved).


Thomas A. Alspaugh and Annie I. Antón. Scenario support for effective requirements. Information and Software Technology, 50(3):198–220, Feb. 2008.
Thomas A. Alspaugh, Susan Elliott Sim, Kristina Winbladh, Mamadou Diallo, Hadar Ziv, and Debra J. Richardson. Clarity for stakeholders: Empirical evaluation of ScenarioML, use cases, and sequence diagrams. In Fifth International Workshop on Comparative Evaluation in Requirements Engineering (CERE’07), pages 1–10, 16 Oct. 2007.
doi:10.1109/CERE.2007.3 url
Thomas A. Alspaugh, Bill Tomlinson, and Eric Baumer. Using social agents to visualize software scenarios. In ACM Symposium on Software Visualization (SOFTVIS’06), pages 87–94, 4–5 Sep. 2006.
doi:10.1145/1148493.1148507 movie
Alistair Cockburn. Writing Effective Use Cases. Addison-Wesley Longman, 2000.
T. H. Pang, N. A. M. Maiden, K. Zachos, and C. Ncube. Do rich media scenarios support requirements discovery? In 11th International Workshop on Requirements Engineering: Foundation for Software Quality (REFSQ’05), pages 152–166, 13–14 June 2005.
Amanda M. Williams and Thomas A. Alspaugh. Articulating software requirements comic book style. In Third International Workshop on Multimedia and Enjoyable Requirements Engineering (MERE’08), pages 1–5, 9 Sep. 2008.
doi:10.1109/MERE.2008.3 url

flip bgunflip