When Words Aren't Enough - Video Documentation for Software Engineers

Supplemental Material

A video usually has a surrounding website it belongs to, filled with additional information and context. When a work of art is displayed in a museum, the museum not only is a properly lit, quiet environment for viewing a piece, but furthers education by adding supplemental material. This material may include signage describing the history of the piece, and the thoughts of the artist who created it. These extra bits of information let the viewer of the piece better understand the artist's perspective, experience and purpose (Rose 2012, 242-251). Similarly, the website a video documentation is displayed on is also designed to be a fitting environment for viewing a video. That site may also contain additional information to make up for weaknesses in the video format.

Video documentation has several weaknesses. Video documentation is not searchable: the content of the video must be watched to see if it answers the viewer's questions. Viewers need supplemental material because "titles, descriptions, or summaries cannot reveal the details of the learning content. Searching is based on metadata attributes and depends on the remembering of the screenshots and their context" (Despotakis and Palaigeorgiou 2015, 89). There are several things outside of the video that can be added to make up for these weaknesses.

Supplemental Text

Supplemental text is an expanded summary of what the video will contain. This can help a viewer decide if it is worth their time to watch the video. Supplemental text may also link to other resources the viewer may find useful.

Transcripts

(#4) When a viewer is curious if a video contains content that will help them, a transcript can be useful. The transcript can be skimmed to find relevant content without having to watch the entire video. It can also be useful for viewers who do not natively speak the language of the video documentation: "outside of the USA, there are many programmers for which English is their second language. For these programmers, reference documentation and on-line help is the preferred structure. Instructor-led classroom training is more difficult for them to learn from because of the speed of speech and the differences in accents" (Broehme et all. 2002, 138). By providing written transcripts, viewers can read what was spoken and more easily understand the documentation.

Timestamps

(#11) A video creator can mark the times when certain topics are discussed within the video. These timestamps may even mark when a line was said in the transcript. When clicked, the timestamp may cause the video to start playing at that specific point in time. This keeps the viewer from having to search through the video to find when relevant information is being discussed. Transcripts eases video searchability, and better let the video be used for reference when a viewer wants to revisit a specific part of the video.

Code Samples

(#17)Code samples are code that is shown within the video, but available in text form. Samples can range from a fully downloadable application to little snippets of text. Samples are a highly valued feature for viewers, who find it very informative to have a code they can use in their own work (Broehme et all. 2002, 140). Code samples saves the viewer time by letting them copy and paste the text, instead of having to pause a video and retype any text shown.

Comments

(#11)Comments are a common feature in any online location. Comments for a video can be useful in expanding the social nature of video documentation. Other viewers can ask and answer questions about the topic in the video. They can also provide feedback to the video creator, such as mentioning that a video is too long. It can be useful for the viewer to read other's notes and questions about the video so they do not have to look for clarification in another location.

Video Player Size

(#16)The viewer may need to be able to watch the video and work at the same time. This usually means the video cannot be expected to be viewed at a full screen size, but will be viewed at the size it is available on the host website. This size may be too small, as seen to the left.

If the video needs to be viewed at a large size, the viewer will need to stop, shrink and minimize the video every time they perform an action. When a video is showing a long step-by-step process, this can become very tedious. Audio can help with this by removing the need to constantly watch the video. Ensuring any text the viewer is likely to copy is easily visible at a smaller video size will also help.