Which artifact is a detailed narrative description of the work required for a project?

Thomas A. Alspaugh

Under Construction

Introduction

Why use narratives?

Why not narratives?

Narrative possibilities

A single point in time

A case of use

User Stories

Narrative Streams

Unstructured Text

Audio and video

Narratives in Steps

Event Sequences

Use Cases

Problems with use cases

Storyboards

Animations

Introduction

Why use narratives?

• People have strong natural skills for reading, telling, understanding, and writing narratives.
• People intuitively infer a lot of information from narratives, especially social information, goals of actors, context, and different ways the story could play out.
• People are good at applying a narrative to their own situation and experience.
• Narratives are good for explaining; in fact, you may notice that most explanations people give for any kind of thing are narratives. In requirements work, they are good for explaining non-narrative requirements of all sorts, contexts, and the reasons behind choices.
• Narratives are good for provoking thought.
• They do not require a specialized background or training for producing, understanding, or using them.
• People like them.

Why not narratives?

• If narratives are used to state the complete requirements for a system, the narratives become numerous. In our experience we note that people tend to keep adding narratives until the collection of them becomes too cumbersome to work with.
• Because each narrative presents a single path through the possible events involving a system, many narratives are needed for any reasonable degree of completeness in the ordinary sense.

  In comparison to requirements in the form of models, a single model typically represents an infinite number of paths, and it would require an infinite number of narratives to express the same thing.

• Narratives can't be compared automatically, in general; a person has to read two narratives to determine whether they are equivalent, contradictory, overlapping, or in subsumption.
• It is hard to identify gaps in a collection of narratives, and thus hard to assess completeness.

Narrative possibilities

Possibilities:

• People get bored by stories that give every detail; they prefer to get just the important waypoints and fill in the gaps themselves.
• Although the custom is to begin a collection of requirements narratives by writing the sunny day story in which everything goes well, people can usually infer the sunny day story from reading stormy day stories in which things go wrong. These appear to be more informative.
• Storytelling as performance.

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 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:

• One use case can include another. Typically one use case U will include another one V by having V as a single step of U, with V typically referenced by name (only).
• One use case can generalize another (in which the second one specializes the first). This relationship is far less well defined, and it is difficult to say what this means except in quite general terms; the explanations I have read have been unsatisfactory and not clear. Where the relationship is specifically stated, the definition uses extension points in the more general use case, at which more specific behaviors are inserted. This relationship does not appear to be widely used in practice.

  Before UML2 this relationship (or one very similar) was named extends.

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:

• Various forms of alternative steps, in which two or more alternative evens are listed (as in 4a, 4b in the example below); or in which an alternative extension is given, as in the example below, in which some other steps are substituted for one or more steps of the main sequence, possibly for all remaining steps after the substitution; or in which an exception extension is given, as in the example below, with the main sequence being hijacked at some point and taken to a different conclusion.
• Includes, in which one use case is a step of another.
• Iteration, in which a step or sequence of steps are to be repeated.

Here is a use case from a project in industry:

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.

Storyboards

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.

Animations

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.

References

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.

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.

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.

What are the 3 levels of work breakdown structure?

What is the purpose of work breakdown structure?

What are the 4 WBS levels?

What is a project scope statement?