A documentation video needs to help a reader answer a product question or complete a task. Some readers follow lessons in order; others reach a single page while troubleshooting. Each lesson needs enough context for the second reader without repeating an entire introduction for the first.
The fictional error-triage tool Sift groups matching error occurrences and lets an engineer resolve a group. Its example policy reopens a resolved group when another matching occurrence arrives. A lesson titled “Why a resolved error group reopens” explains that condition and shows where the engineer can inspect the new occurrence.
Define the question and the expected result
Support conversations, usability sessions, and documentation feedback can identify questions worth teaching. Analytics can identify pages to investigate, but a page exit alone cannot tell the team whether a reader found the answer.
The Sift lesson has a specific completion check: the learner can identify which event reopened group PAY-204 and explain why resolving the group did not prevent another occurrence. Installation, alert routing, and grouping configuration have separate lessons because none is necessary to answer that question.
The prerequisite text defines a group as related occurrences of an error. It links to the grouping reference for readers who need more detail. The lesson also names the product version and permissions required to view and resolve a group.
Establish the example before making scenes
A producer needs screenshots or a recording of the relevant product states, together with the documented reopening rule. In a real engagement, a product expert verifies the example against a test workspace. The fixture below defines the fictional Sift behavior used in this article.
| Event | Group state | Occurrence count | Latest occurrence |
|---|---|---|---|
| The initial fixture loads. | Open | 4 | 10:02 UTC |
| The engineer resolves the group at 10:05 UTC. | Resolved | 4 | 10:02 UTC |
| A matching occurrence arrives at 10:07 UTC. | Open | 5 | 10:07 UTC |
| An unrelated error arrives at 10:09 UTC. | Open | 5 | 10:07 UTC |
The unrelated error belongs to another group. Keeping PAY-204 unchanged in the last row distinguishes a matching occurrence from any new error. The same group identifier and timestamps appear in the video, transcript, and exercise.
The source record must also settle what “matching” means at the level the lesson needs. If the actual product has configurable reopening windows or release rules, the lesson identifies the active setting. A simple fixture cannot silently stand in for every configuration.
Build a lesson that explains the change
The scene plan follows one group through resolution and reopening. It keeps the details needed for comparison visible and avoids introducing a new dashboard for each step.
- Show the open group with four occurrences. The title and group identifier establish which object the engineer is reviewing. The occurrence list provides the latest timestamp.
- Record the engineer resolving the group. The status changes to Resolved while the count remains four. A reading hold lets the viewer compare those fields.
- Introduce the matching occurrence. The list gains a fifth row at 10:07 UTC, and the status returns to Open according to the fixture's rule. The new row remains visible beside the status.
- Open the new occurrence. The detail view supplies the information the learner needs to investigate it. The camera retains a group label so the new view has a clear relationship to the previous one.
- Show the unrelated error as a separate case.
PAY-204keeps five occurrences. The comparison prevents the lesson from implying that every incoming error reopens every group.
Narration follows the visual sequence. “The new matching occurrence reopens this group” refers to a visible row and status change. A sentence about automatic recovery would require a different example and a verified rule.
The storyboard template can hold each scene's entry state, action, and resulting state. Runtime follows the reading and comparison work; the occurrence list deserves a hold even though nothing moves during that hold.
Keep the procedure available as text
The surrounding documentation gives the learner a copyable or repeatable task. For Sift, it identifies the test group, explains how to resolve it, and supplies the approved way to send a matching test occurrence. It also states the expected count and status after each action.
A learner check uses a fresh example. If a resolved group has two occurrences and receives an unrelated error, the learner predicts whether that group's count changes and checks the result. Repeating the video with the same answers visible would test recall of the footage more than understanding of the rule.
Captions and a transcript make spoken information available in text. Screenshots or a short state table preserve the comparison for readers who do not play the video. Exact configuration fields belong in the reference material, where a reader can search and compare them.
Organize related lessons by dependency
Grouping supplies vocabulary for resolution, while assignment answers a different question about ownership. A guided path can teach grouping before resolution and link assignment where ownership becomes relevant. Direct links beside the player let a reader repair a missing prerequisite without restarting the course.
Each concept needs a primary explanation that other lessons can reference. Shared definitions prevent one lesson from calling an occurrence a group while another treats them as distinct objects. A tutorial-series plan records those dependencies and the scope of each lesson.
Record what makes a lesson become outdated
The lesson owner keeps a list of product facts and interface locations used by the cut. For Sift, changes to the reopening rule, group status labels, or occurrence detail screen trigger review. A change to an unrelated billing page does not.
An update may require a new screenshot, revised narration, different timing, and corrected captions. The owner compares the revised video with the product and repeats the learner task before marking it current. Retaining the editable source helps with those changes, but the production agreement must explicitly include source delivery if the customer needs it.
Before publication, a reviewer unfamiliar with the fixture attempts the task using the page. The finished lesson succeeds when that reviewer can explain the reopening condition and locate the new occurrence without undocumented help.