Best practices for including videos

Including links to videos in Splunk documentation is another way to help users understand information in a format other than written text. If you link to a video in your content, make sure the video complements rather than replaces written information. Aim to include short videos that enhance a user's understanding of a single topic, and make sure that viewing a video isn't required for users to complete a task.

Any video that you link to must have the option to show captions and transcripts to assist users with hearing impairments. For more information on accessibility requirements for videos in Splunk docs, see Write accessible documentation.

When to include a link to a video

Consider including a link to a video in the following situations:

• The UI requires complex interactions or steps in multiple browser tabs.
• You want to show steps that happen simultaneously in different parts of the UI.
• You want to show the steps in a complex or intricate process.
• You want to show a complicated relationship between different parts of a product.
• You want to include a visual and auditory representation of conceptual information.

Before you include a video

Before you include a link to a video in your documentation, meet the following requirements:

• Provide complete written instructions that a user needs to be successful in the topic before including a link to the video.
• Consider that the information captured in a video might change in upcoming releases. Know the time and cost involved with recreating videos if the UI or process changes significantly.
• Don't use a heading to separate a video from the main content.
• Link to videos that the Splunk Docs team or another team at Splunk, such as Splunk Education, have created. Don't include links to videos that other companies create.
• Link to videos that are short in length, ideally no longer than 4 minutes in duration.
• Introduce the video by using the name of the video as the display text of a link, and provide a description so a reader can decide if they want to view it. See an example of linking to a video in Formatting links in Splunk documentation.
• Don't embed a video on a page.

After you include a video

After you link to a video in your documentation, complete the following tasks:

• Check that the link to the video works, and that the video contents are accessible before every release.
• Review that the video is related to the contents on the page, especially if the topic has gone through revisions.
• Double check that the video you're linking to shows captions and transcripts.

When not to include a link to a video

Don't link to videos in your documentation in the following circumstances:

• The video was created by another company.
• The video covers multiple topics. Remember that a reader can't search for the relevant parts of a video the way they can in documentation.
• To replace or avoid writing an explanation about how to complete a task.
• If the video is unrelated to the contents on the page.
• If the video contains customer data or Splunk data.
• If the information in the video can be conveyed in 5 seconds or less and doesn't require a voiceover, consider creating a GIF instead. See GIFs.