Composed Narrative

Context

You want to explain a particular aspect of a software system. It could be an explanation of how to use the system, or a problem or bug that needs to be resolved.

Problem

How can you explain an issue with a software system in an intuitive way that is easy for a reader to follow?

Forces

— Pure textual narratives can be hard to follow and visualize.

— A picture is worth a thousand words.

— An individual screenshot without context can be misleading.

Solution

Create a narrative composed of views of various objects or tools, where each view leads to the next by performing a particular action or step. Share the narrative as a static screenshot, record it as a video, or perform it live with an audience.

Steps

Choose a starting point within a given tool, such as a notebook page, an inspector view of an object, a debugger window, or a source code editor on a class or package. Navigate to a new state by performing a step, such as clicking on an element of a view, performing a custom action, initiating a custom search, evaluating a code snippet in a contextual playground, or any other GUI action. String together these states and steps into a narrative. Capture the narrative as a screenshot or a video, or a live, scripted GUI entity, and share it. Be sure to capture the entire view of each tool or object to provide the necessary context. If necessary, edit or decorate the narrative to highlight certain aspects or steps performed.

Examples

Below we see a composed narrative answering the question of how to locate the implementation of a shortcut of an editor. The narrative starts with a visual scene for which we see the rendering tree (similar to an HTML DOM). A paragraph object from the editor is selected and reveals its list of shortcuts. A shortcut object presents its defining source code and concludes the answer.

Most of the figures in the paper are illustrations of Composed Narrative. For example, Figure 3 shows how a given Custom View is implemented in a few lines of code. Figure 5 shows how a raw view differs from a Custom View. Figure 12 illustrates how examples can be composed to create new examples.

Consequences

A Composed Narrative tells a story of how one can get to an interesting state.

You may need to carefully adjust the individual views to highlight what is interesting.

Composed Narratives consisting of more than three views may be unwieldy when shared as static screenshots.

Known Uses

Narrative art works, from the Bronze Age through to modern graphic novels, tell stories by juxtaposing images. Montage Theory, dating from the early days of cinema, creates narratives in film by creatively juxtaposing individual shots.

Related patterns

The first view of a composed narrative is often a Project Diary notebook page, or a Custom View of an Example Object. The steps performed may be a Custom Action, a Custom Search or evaluating a snippet in a Contextual Playground. A scripted Composed Narrative can itself be turned into an Example Object.