Narrative Picture

This is a rough DRAFT to be expanded and reviewed.

Problem

How do you design a screenshot to explain a code issue?

Forces

A picture is worth a 1000 words. It's hard to design a picture that tells a story.

Solution:

Compose a narrative picture as a screenshot showing the flow from some code snippet to the resulting Inspector view.

Steps

The goal is not only to show the resulting issue (an error or a strange situation) but also how you got there. The picture should show the code snippet, which could be a snippet in a notebook page, or a playground within an inspector or another tool, and also the result of evaluating the snippet, queued to the interesting view. You may want to highlight part of the code or the resulting situation either by selecting the code, or post-processing the screenshot (though this is rarely needed). Sometimes there are several steps to the story. In this case you can use multiple screenshots, or you can resize the pages to show three or more in a single window.

Related patterns

...