Assets

Assets can be attached to Constructs to provide context or to specify how an entity should behave.

To create an Asset, simply drag an Asset from the Constructs Menu in the toolbar onto the diagram. You must name and create it or it will disappear when you click away. Empty assets are not allowed on the diagram.

To attach an Asset to a Construct, drag the Asset onto the Construct. Edit Asset content using the side panel.

Holistic Level Assets​

Holistic level assets can be found on the toolbar for easy access.

Actor​

For each Moment in a Narrative, there is a high likelihood an actor is involved. The actor may be human or a system. Note them down, and use the actors in your narrative to tell a better story. Our minds are built for narratives that involve personas and characters.

Actors appear on top when dragged into a Construct.

Spec​

A spec, or specification, is a detailed description of how a particular feature or aspect of a system is supposed to work. It serves as a guideline or blueprint for development and testing, ensuring that the final product meets the intended requirements and behaviors.

Specs can be written using Given-When-Then (GWT) or Should notation.

Writing Specs with Given-When-Then (GWT) Notation​

The Given-When-Then (GWT) notation is a structured format for writing specs that describe software behaviors without detailing how the functionality is implemented. This format is divided into three parts:

• Given: Describes the initial context or preconditions before the action of the spec takes place.
• When: Specifies the event or action that triggers the behavior being specified.
• Then: Outlines the expected outcome or state after the event/action has taken place.

Example

Given a user is logged into their account,
When the user adds an item to their shopping cart,
Then the item should appear in their cart.


Writing Specs with Should Notation​

Should Notation is a more flexible and often more concise way to describe specifications. It focuses on what the system should or should not do, allowing for a variety of expressions. This notation is particularly useful for expressing expectations and requirements directly.

Example

Confirmation Email
  it should send a confirmation email after a user completes a purchase.
Shopping Cart
  it should not allow adding more items than are available in stock.


Other Assets​

Docs, queries and schemas can be found in the overflow pallet.

Doc​

Docs, like other assets, can be attached to Constructs to provide more context.

They can contain lists, formatted text, images, videos and links.

Formatting docs​

Docs are rich. Type / to open the insert menu and insert headings, links, images and more.

Highlight text to format using the balloon menu.

Schema​

A schema defines the structure of data that can be queried by clients. Queries, formulated based on this schema, request specific parts of the data. The schema ensures that queries ask only for what's available and in the correct format, making data fetching efficient and type-safe. Essentially, the schema acts as a contract between the client and server, guiding what data can be requested and how.

Query​

A query is a structured text syntax that defines the shape and content of the data you want to retrieve from the API. It precisely mirrors the hierarchical structure of a Schema, allowing you to specify fields on objects, nested objects, and even instruct the server on how to transform the data returned.

‍