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

Video Qualities

Videos are more than just the footage they show. They have a certain length and a certain level of quality. Looking at not only what is shown in the video, but qualities of the video itself can provide further guidance towards what makes video documentation useful.

Video Length

Brevity is highly valued in video documentation. The longer a video is, the less likely it is that a viewer will watch the whole thing. One student commented about video documentation that "I was afraid to fast-forward the video; I was afraid of skipping the details" (Despotakis and Palaigeorgiou 2015, 90). Viewers are usually seeking specific information and they are less likely to easily find that specific information in a lengthy video.

Longer videos also do not contribute well to learning. In a study where students were learning via screencasts, one student commented, "I cut the lengthy videos into parts and I study them accordingly. I could not remember anything after such (long) videos" (Despotakis and Palaigeorgiou 2015, 88). Another commented, "I do not like the 20-minute videos because I cannot watch them and then explore the application; I have to stop, then experiment and then continue, then stop...It is very uncomfortable to combine practice [of the shown material] with long videos" (Despotakis and Palaigeorgiou 2015, 88).

Some video creators will break up a long videos into a series of videos. This makes it easier for viewers to learn as much or as little as they need. One student being studied noted that "I decide on the videos that I am going to study according to the time I have at my disposal" (Despotakis and Palaigeorgiou 2015, 92). When a video is too long, potential viewers may avoid the documentation altogether as they feel they don't have the time to view longer material. Longer videos should be broken up into a series of task or subjects. This series of videos will be more appealing to viewers.

Clarity of the Video

(#13)Video documentation tends to display a significant amount of text. When this text is large enough and clear enough to read, it is a major aid to the viewer's ability to use the documentation. If the text is code, clarity may be necessary for when the viewer needs to use the code themselves.

Since a video may not be displayed at full screen, the size of the text in a screen capture may not be appropriate. As noted by Ellen Lupton, "a line of text that looks tiny on a television screen may appear appropriately scaled in a page of printed text. Smaller proportions affect legibility as well as space consumption" (Lupton 2010, 39). Similarly, a line of code that looks fine to a user of an application may not look fine in a recorded video of the application. This is made more complicated since the font size in a software application may not be adjustable.

Text may be able to be enlarged by zooming in the framing of the video (as seen in #13), or by putting that specific text on a slide (as seen in #3). But even if text is enlarged, the viewer may be put off by the poor quality of the text's appearance. The table below shows the quality difference between command line prompt text in an HD video and a non-HD video. Even though the non-HD text is larger, the HD text is still easier to read.

Furthermore, the environment the video is contained in may also affect the clarity of the text. In the example to the left from #13, the code shown in the video is impossible to read in the native YouTube environment. It is far too small. The code is still difficult to read when the video is viewed in full-screen mode, because the video is not in HD. The video uses zooming to improve visibility but, as the author notes in the YouTube comments, it would have been better if the entire video was available in HD.

Non-HD (#6)HD (#15)

Audio

(#14)A video naturally means visual information. Most videos also include audio, but not all of them. In the sample of videos selected, two videos do not contain any spoken audio: #14 and #15. Instead, these videos use text on the screen to present additional information. This raises the question if audio is necessary.

In an early research study of video documentation, a viewer noted, "the designer's intent was clearer in the videos than in any written design documentation I've ever seen. Being able to hear in the designer's own words, his point-of view, focus, approaches evaluated and rejected, etc., provides a framework in which new design decisions can be made" (Demarco and Geertgens 1990, 127).

It can be valuable to hear thoughts. This not only makes the video more personal: a commentary aids the in viewer's understanding of the topic. While it is possible to present this information in a visual format, an ongoing verbal commentary is more likely to capture the video creator's thoughts than text snippets that need to written out and designed—a far less spontaneous process.

If video documentation's benefit is to capture tacitly understood information, then audio is necessary a majority of the time. The computer may be able to record the video creator's actions, but the microphone will capture the video creator's thoughts. The creator's thoughts may be limited by space on the screen if they choose to not express these thoughts verbally, which may lead to important information being removed from the presentation.

However, there is a necessary level of polish needed in the documentation's audio. Unplanned audio, such as in #8, may be filled with stutters, awkward pauses, or confusing phrasing. Poor audio quality, such as the audio containing background static or being too quiet (as seen in #13), can make well-planned speeches be difficult to listen to. A good microphone and practice of the presentation is necessary for successful video documentation.