Producing videos for a course

A video at the top of a lesson is not made next to the course but out of it. The repository has a dedicated folder, video/, whose tooling turns finished lessons into a script and a slide deck per lesson. This lesson follows the path from a frozen lesson to the video ID in the front matter.

Where the video sources live

The video/ folder mirrors content/. A lesson at content/en/courses/<slug>/<section>/<lesson>.md gets a folder video/en/courses/<slug>/<section>/<lesson>/ with two files:

video/en/courses/your-course-name/
├── README.md                      video list and status
├── _trailer/                      preview for the course page
├── 10-getting-started/
│   └── 10-introduction/
│       ├── script.md              scenes, speaker text, directions
│       └── slides.md              slides with the speaker text as notes
└── _outro/

Both files are Markdown and live in Git. When a lesson changes, script and deck change in the same merge request, because the videos quote the lesson’s commands and output verbatim. Recordings and finished video files do not belong in the repository; that is what the TIB AV-Portal is for, see below.

The tooling in the folder is independent of the website build. Install it once:

make video-install

Scaffolding from the lessons

The next step only pays off once the course content is final: a video cements the state of its lesson, and later corrections to the text never reach the viewers.

Run:

make video-new-course COURSE=your-course-name VIDEO_LANG=en

The command reads the course’s sections and lessons and creates, per lesson, the folder with script.md and slides.md, plus _trailer/, _outro/ and the course README with the video list:

created _trailer
created 10-getting-started/10-introduction
created 10-getting-started/20-setup-environment
…
created _outro
created README.md

13 lesson folder(s) created for "How to Create a Course"

Title, description and the target length from duration are filled in. The lesson’s ## headings become scenes in the script and slides in the deck. The lesson’s code blocks, that is commands, terminal output and file contents, appear verbatim on the matching slide. The first question from ## Check, with its answer, forms the closing slide. Existing folders are left alone, so you can run the command again after adding a lesson.

What the command does not copy is the prose. The speaker text is written for speaking, not for reading the lesson aloud.

Filling in script and deck

The script describes each scene with picture, speaker text and directions: what is on screen, what is said over it, when the camera is visible. The rules are in video/GUIDE.md, with sources from research on instructional video. The most important ones:

• one learning goal per video, under six minutes
• code and terminal output as text on the slide, never as a screenshot
• no lesson numbers on screen or in the speaker text, so videos can be inserted later
• a question from the check at the end, with a pause before the answer
• the trailer opens without jargon; the course’s terms are listed in terms.json next to the course README, and the check reports them in the hook
• terms with a definition get a glossary card in the video at their first mention, and the lesson page shows the same definitions under the video

The deck is a Slidev presentation in Markdown. The speaker text sits in a comment under each slide, and [click] markers in it belong to the reveals. To edit a deck, and later to record it, start it like this:

make video-slides LESSON=introduction

The command opens the first deck whose path contains the word. http://localhost:3030/ is the slide view, http://localhost:3030/presenter/ the presenter view with the speaker text next to the slide. While recording, the second view is the teleprompter.

Checking and exporting

Before recording, build every deck in the repository once; broken slides show up here:

make video-check

For proofreading outside the browser, the export writes a PDF handout with slide and speaker text side by side, and the speaker text as Markdown:

make video-export LESSON=your-course-name

The result lands in video/renders/export/, a folder Git ignores.

Recording and publishing

Recording happens per scene, not per video, with OBS and the presenter view on a second monitor. The setup with scenes and hotkeys is described in video/RECORDING.md.

Upload the edited video to the TIB AV-Portal. Its ID goes into the lesson’s front matter, as described in the previous lesson:

video:
  tibav: 42061

That makes the lesson the only place that records whether a video belongs to it, and which one.

As a rule of thumb: videos only after the content freeze, script and deck always in the same merge request as the lesson, recordings never in the repository.

Check