Narrative Script Basic Anatomy

Narrative Script Basic Anatomy

A narrative script is a modeling technique that visually represents both a contextualized user journey and its associated technical architecture, all at once.
A single script details how a specific valuable outcome is realized. In combination, these scripts form a complete catalog of your entire software product requirements.
In this section of the guide, we will take a closer look at an example narrative script. We will dissect the basic building blocks of the NDD constructs palette and explain how they work together.

Example Narrative Script

notion image
What we see here is an end-to-end user journey describing moments unfolding over time that lead to a valuable outcome. This outcome is the title of the script above the timeline:
Customer receives loyalty points after an in-store purchase.
The timeline of the story that results in this outcome is presented over 3 lanes:
  • Context lane
    • The middle lane has blue constructs that tell us what happens. We call these “Moments".
  • Interaction lane
    • The upper lane shows the Interfaces used for interactions. We use white constructs for Interfaces.
  • System lane
    • The lower lane displays yellow “Action” constructs. They stand for operations performed by the system.
Let’s now dissect the different elements that make up a narrative script in a bit more detail.


An outcome states the value achieved and serves as the end goal of the entire narrative script. Clearly defining valuable outcomes is crucial for building valuable products. A simple sentence that succinctly states this outcome is the essential starting point for creating a narrative script.


The narrative script is divided into sequential steps, demarcated by the border lines. We call them “frames.” These are quantized units of time that help us organize the timeline. Every frame needs to have at least one construct in the respective lane for the narrative script to be continuous.


A moment marks a period of importance in a narrative. Its purpose is to provide context for the valuable outcome we want to achieve. We denote Moments with blue constructs:
notion image
In this case, the moment includes an Actor; Kim the customer. For clarity and reusability, we separate the Moment from the Actor like this:
notion image
This helps us keep track of the different personas we’re building for. We avoid abstract “user” personas because we want to describe how value is realized to specific Actors, humans or systems alike.
A Moment can be written in the past, present, or future tense. The past is especially useful when establishing an initial context to introduce the script, like this:
notion image
A Moment doesn’t always have to have an associated Actor. This can be useful to represent a combination of things happening behind the scenes in the system, for example:
notion image
The succession of Moments frame after frame is the core of a narrative script. The Moments come together to realize the outcome where the Customer receives loyalty points after an in-store purchase:
notion image
This orderly sequence of Moments experienced by the Actors provides extensive context about the user journey. Although it appears simple, it's rich in meaning, succinctly narrating how a valuable outcome is achieved. Since the human brain is naturally inclined towards storytelling, a series of Moments leading to the desired outcome offers an intuitive approach to defining software product requirements.
In Narrative-Driven Development, Moments are the foundational elements of the requirements gathering process, acting as the backbone onto which all other aspects are layered.
Building on this foundation, let's now explore how the constructs presented in the Interaction and System lanes enrich the story. Although slightly more technical than Moments, these building blocks are designed to be accessible to non-technical stakeholders, thereby facilitating cross-functional collaboration.


Interfaces are denoted with white constructs placed on the upper lane of the narrative script.
Some Moments require an Interface to be present, while others don’t. When defining the Moments, we assume the points of view of the respective Actors. Consider the following frame:
notion image
A quick look at the moment immediately tells us we need a graphical user interface (GUI), so that Kim can see her loyalty points balance:
notion image
Notice that the text on the Interface construct defines a specific part of a UI: the loyalty account page.
However, a single narrative script may involve multiple types of UIs (e.g. mobile app, Point of Sale). While this is not an immediate concern when defining the Interfaces, eventually we may want to denote the various types that the Interfaces belong to using colored tags above the construct, like this:
notion image
This way, we’re able to convey repeating information similar to Actors, while keeping the Interaction lane simple.
Bear in mind that the tags are an optional addition, and you don’t have to be concerned with getting the narrative script perfect in the early stages. Narrative scripting is an iterative approach that adds complexity layer by layer.
Remember that NDD accommodates imprecision and the script might not even be correct in the initial draft. As you progress, the picture becomes clearer, so always prioritize progress over perfection.


An action is anything that needs to happen on the part of the system, so as to support the progression of moments over time.
We denote Actions using yellow constructs placed on the System lane:
notion image
Actions can be thought of as macros for business processes and system behaviors. They are a placeholder for details that will be fleshed out collaboratively with engineers at a later stage. Like interfaces, they track the context provided by the moments but they do so at the system level.
While we use just a few simple words to describe an Action, it may stand for otherwise very complex things happening behind the scenes in the system, such as managing transactions, fetching data, calling external systems, triggering reactions, sending notifications, etc.


Specifications are plain English descriptions that are attached to NDD constructs. They are used to define the intended behavior of a given construct. These can be simple descriptions, bullet points, “should” statements, or “Given, When, Then” blocks. They can start out as one-liners and progressively become more detailed.
notion image
In the early stages of scripting, specs are loosely defined and optional. Later on, we’ll see how different kinds of specs are used to inform code implementation with much greater precision.

Interactions, reactions, and results

For the narrative script to be coherent, we need to indicate the flow between the Interaction lane and the System lane. Similar to flowcharts, this is done using arrows, or transitions, as they are called in NDD.
notion image
We may include notes to describe the flow between transitions, in line with the following 4 patterns:
notion image
Let’s unpack this rubric one by one:
  1. An Actor’s interaction can take them from one Interface to another.
  1. An Actor’s interaction with an Interface can also trigger an Action.
  1. An Action can produce a result to be fed into an Interface.
  1. An Action can also trigger another Action as a reaction.
This simplified set of instructions is designed to reduce the mental load as the system is being drafted. With just a few constructs you can easily flesh out and rearrange things until they make sense to all parties involved.

Putting it all together

In this chapter, we gained a basic understanding of the foundational constructs and concepts used in narrative scripting. Let's briefly recap in the context of our example:
notion image
  • A narrative script describes a single flow of time that unfolds moment by moment and leads to a valuable outcome.
  • The narrative script timeline is quantized with units of time called “frames”.
  • The different NDD constructs are placed on 3 lanes of the timeline. We start with the following constructs:
    • Moments and Actors have their dedicated lane in the middle called the Context lane. We use them to define the context leading to the valuable outcome.
    • Interfaces are placed on the upper lane called the Interaction lane.
    • Actions belong to the lower System lane, where we define the behavior of the system.
While we encourage everyone to work in whichever lane they are able to, the Context lane is particularly interesting to product folks. The Interaction lane appeals to UX folks, and the lower System lane is geared towards tech folks. This is not a strict division where everyone should stay in their lane though! Rather, it’s a coarse-grained view that reflects the multidisciplinary nature of software creation.
In the next chapter, we’re going to trace the process of creating the above example in detail, so that you can start creating your own narrative script.