Narrative Builder Tutorial
⏰ Time required: 20 mins to 1 hour
This document explains how to choose supporting evidence, how to decide how many messages will fit in each marker, and what to include in the summary, time, and notes sections (including questions that can eventually go into the product).
You've had an incident; now it's time to use Jeli to make it easier to prepare for your incident review meeting. In this tutorial you will learn how to review your Slack transcript to create a Narrative timeline of your incident and prepare Questions you want to ask during the meeting.
Narrative Builder view
Jeli’s Narrative Builder makes it easy to tell the story of how your incident happened while taking into account multiple points of view. Narrative Builder allows you to use the primary data as evidence for the building blocks of your narrative, this allows for a blame-aware analysis of the incident that looks at what actually happened (rather than focusing on counterfactuals).
🔥TIP: We recommend you spend some time before your Incident Review Meeting creating your Narrative. We have seen that spending some time prepping helps with making the (expensive) meeting a productive one.
Choose supporting evidence
Go through your transcript line by line and ask yourself if each message is important in telling the story of the incident and if it fits within one of the marker types: Detection, Diagnosis, Repair, and Key Moment. If so, choose the marker and bring the message in as Supporting Evidence.
🔥TIP: It might be helpful to ask yourself: Does this message help explain how we found out we were in an incident, how we realized what the problem was or wasn’t, how we worked towards resolution, or how people interacted with each other and the problem?
You may include multiple pieces of evidence under the same marker when they all relate to the same point.
You can also add evidence from outside of Slack messages by clicking the "Add supplemental evidence" button. Here you can add images, text, and links to add context to the story of the incident. This might be screenshots of graphs, links to a specific query, or a copy and paste of relevant logs.
Update your marker details
After you’ve added your supporting evidence you may update the timing fields. The start time will update automatically with the timestamp of the first message. If you’ve added multiple pieces of evidence you can add the end time here as well.
Update the summary field with a couple of sentences describing what is happening in the supporting evidence. For example: “SREs and Software Engineers decide to move forward and revert the change made earlier in the day”
🔥TIP: We recommend using plain words as if you are telling the story of what happened to a coworker or in front of your incident review meeting.
Add additional notes
We suggest you use the notes section to ask any question you have based on the supporting evidence.
🔥TIP: Even if you think you know the answer, if something is unclear it is helpful to ask it during the review meeting so others can learn from it.
Add more markers to help tell your story
You can choose as many markers as you need to tell your story, you do not have to go in a linear detection-diagnosis-repair manner either. Often incidents will jump back stages as information becomes available.
For example, we may realize halfway through the repair that there is another component impacted and we need to reach out to a new set of folks.
Here is an example where we have annotated the rich insights that the markers highlight.
Edit and delete existing markers
To edit an existing marker you can hover over the three dots next to their markers and click “Edit” which will open up the Narrative Marker Details modal.
To delete an existing marker you can hover over the three dots next to their markers and click “Delete”.
Opportunity Start and Opportunity End Time
The Opportunity Start and End Times are automatically generated based on the first channel ingested into the Opportunity. To change this information, you can choose the markers and edit them as necessary.
Once your Narrative is complete you may use it in the next step of your Incident Analysis process, we recommend turning it into your agenda for your review meeting as explained in the Basic Investigation Tutorial.