docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update guidelines for videos (#19813) 

* add video guidelines

* update description

* fix typo and add guideline
This commit is contained in:
Stephanie Aurelio 2024-04-17 11:23:05 -07:00 committed by GitHub
parent 7cf218b75f
commit 32c9d9ddb7
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 25 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
content/contribute/components/videos.md
View File

@ -1,9 +1,33 @@
---
description: components and formatting examples used in Docker's docs
description: Learn about guidelines and best practices for videos in docs, and how to add a video component.
title: Videos
toc_max: 3
---
## Video guidelines
Videos are used rarely in Docker's documentation. When used, video should complement written text and not be the sole format of documentation. Videos can take longer to produce and be more difficult to maintain than written text or even screenshots, so consider the following before adding video:
- Can you demonstrate a clear customer need for using video?
- Does the video offer new content, rather than directly reading or re-purposing official documentation?
- If the video contains user interfaces that may change regularly, do you have a maintenance plan to keep the video fresh?
- Does the [voice and tone](../style/voice-tone.md) of the video align with the rest of the documentation?
- Have you considered other options, such as screenshots or clarifying existing documentation?
- Is the quality of the video similar to the rest of Docker's documentation?
- Can the video be linked or embedded from the site?
If all of the above criteria are met, you can reference the following best practices before creating a video to add to Docker documentation.
### Best practices
- Determine the audience for your video. Will the video be a broad overview for beginners, or will it be a deep dive into a technical process designed for an advanced user?
- Videos should be less than 5 minutes long. Keep in mind how long the video needs to be to properly explain the topic, and if the video needs to be longer than 5 minutes, consider text, diagrams, or screenshots instead. These are easier for a user to scan for relevant information.
- Videos should adhere to the same standards for accessibility as the rest of the documentation.
- Ensure the quality of your video by writing a script (if there's narration), making sure multiple browsers and URLs aren't visible, blurring or cropping out any sensitive information, and using smooth transitions between different browsers or screens.
Videos are not hosted in the Docker documentation repository. To add a video, you can use a [link](./links.md) to hosted content, or embed using an [iframe](#iframe).
## iframe
To embed a video on a docs page, use an `<iframe>` element: