THE GITHTML FIELD GUIDE
Keep a tutorial useful when its embedded video will not play
Treat video playback as an optional enhancement unless the document is explicitly designed around a supported media workflow. Provide the tutorial's instructions and important spoken information as HTML text. Then diagnose the media URL, format, authorization, and loading requirements without assuming that enabling scripts will solve the problem.
Identify what the media depends on
A video element pointing to a media file has different requirements from an embedded player loaded through an iframe. The latter may need scripts, cookies, authentication, or a network connection to another service. Start by identifying which type the document contains and what the final destination returns. A normal webpage URL is not necessarily a playable media resource.
Also distinguish a missing poster image from missing video content. A blank preview does not establish that the media file is absent, while a visible poster does not prove playback works. Record the exact symptom and the intended reading environment before changing the document. Avoid distributing temporary media credentials or private session URLs as a quick fix.
Preserve the instructional content
For a tutorial, write each required action as a numbered step with the relevant control names and expected result. A transcript preserves speech, but it may not capture silent on-screen actions. Add those actions explicitly and include selected still images when they clarify a difficult interface. The document should remain useful to someone who cannot or chooses not to play the video.
Timestamps can help readers find a demonstration in the original recording, but the surrounding text must still make sense independently. State whether the video shows an older interface or a particular platform version. Do not let a polished recording silently override newer written instructions; identify which source is authoritative when they differ.
Make the dependency visible
If the video remains external, label it as an optional resource and describe any authorization requirement. gitHtml's remote resources and JavaScript are off by default, so runtime media should not be the only carrier of essential information. Do not promise that the app caches a whole player or all associated media assets.
- Identify a direct media file versus an embedded external player.
- Check the destination, format, and access requirements.
- Provide complete written steps and relevant spoken information.
- Add visual descriptions for important actions that are not narrated.
- Link timestamps only as a convenience.
- Verify that a reader can complete the documented task without playback.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.