Incident Storytelling

We asked friends in the learning from incidents community, when working on the narrative section of a writeup, should we give away the ending early (in a sorta journalistic approach where the story is paraphrased in the lede)? Or should we let the reader discover the plot twists gradually more like a mystery novel? (meta: so much joy to be found in on-demand learning, and so many options, too.)

The advice we chose blends the options posed in our question. Offer the reader a more peaceful journey than that taken by the participants in the incident. But create a compelling dramatic tension by making clear what the reader knows that the characters in the story must still discover. See "Conveying Confusion Without Confusing the Reader": article

The narrative is only part of what's needed in the incident story.

Also include Themes collected while reviewing interviews, chat transcripts, pull requests, feature requests, documentation, drawings etc.

Themes will become a source for cross-referencing and identifying related incidents.

Also include as much evidence in the document as possible and links to supporting materials throughout the organization.

Write the document as if it will be read. Give the reader links to all the details. Someone in the future may discover important reasons to follow those links. Make the document a concrete resource and tool for future discovery.

.

Robert Yin offers many options for narrative structure of case studies. These details were offered to us for context, or for further study.

TODO find this link [ book]

Linear-analytic. Common for research. Issue. Literature Review. Methods. Data. Analysis and Findings. Conclusion.

Comparative. Same plot told from different points of view.

Chronological. Suggest writing the most recent details first and working backwards to ensure the author devotes sufficient time to the most recent material.

Theory-building. Each section reveals a new part of the theoretical argument.

Suspense. This matches our chosen option. Tell the outcome first. Develop an explanation of the outcome. Also consider alternative explanations.

Unsequenced. Suitable for descriptive case studies where reordering sections would not alter the value.

The incident stories we want are case studies. Case studies can serve different purposes. Structures lend themselves better to different purposes: explanatory, descriptive, or exploratory. Incidents call for the explanatory sort.