back to the blog

As the documentation editor for Joyent, my work has been split in three ways: technical blog posts, screencasts, and actual documentation. I find the most fun with the first two—as important as actual documentation is (and it may be the most important), there’s little room for creativity and an editorial voice. Technical screencasts can have a bit of fun flair, but still must be accurate and (most importantly) instructive.

The more videos I’ve created, the more I’ve learned about how to craft watchable content.

1. Be as brief as possible.

Although there are instances where longer videos come in handy, such as in-depth step-by-step tutorials or publishing webinars, many users don’t have the patience to sit through long pauses or over-explanation of a topic.

I’ve recently started a project which is internally being called micro-videos. It’s a series of videos that are under 90 seconds (ideally, under 60), which quickly demonstrate how to use a very specific tool. For example, there are a number of ways to get an IP address for your Docker container. Though I’ve written how to do so in our documentation, it can be very valuable to see those options in action.

Two methods give a series of information beyond just the IP address. The third method just delivers the IP address. This video does not exist to advocate for one method over another. Rather, it exists to give visual learners a path to understanding how these commands work.

2. Write a script, request reviews, and edit it. Rinse, wash, repeat.

I go through a six step process before publishing a new video: draft a script, gather peer review of the script, record the audio, record the content, put it all together, and request reviews again. Note the fact that the audio and content is not recorded at the same time. It can be helpful to talk through the process when capturing the video, but you’re setting yourself up for a lot of extra work if you change any part of the script after you’ve recorded.

Not all videos can or should be under 90 seconds (the micro-videos). Some topics require a deeper dive and explanation. I created a three part series about Triton Container Name Service (CNS): introduction to CNS, using CNS with Docker, and assigning a vanity domain with CNS.

I spent many weeks in the editorial process for this series, debating what information was important to repeat in each video and what information could be left to the context of the blog or documentation. These videos work together, though you don’t necessarily need to watch all of them. I wrote the scripts at the same time so that even though they were published at separate times, my editors saw it as a complete series. Speaking of which…

3. Use a video editing tool.

When I was in college, I interned with TechSmith, which introduced me to Camtasia. I love this tool because it was made for screen capture, which is 80-90% of my video work at Joyent. Okay, and I’m biased because my internship was awesome (and paid).

Other tools like Final Cut Pro X and Adobe Premiere Pro are used by a lot of professional video editors and have a lot of additional customization options to play with.

That said, if you are most comfortable with Windows Movie Maker or iMovie, use those tools. What matters is being able to edit and re-visit the raw content in the future to make updates. Don’t feel obligated to pay more for a video editing tool if you’re not producing video content on a regular basis.

4. Use professional audio equipment.

The microphone on your laptop and within standard earbud headphones is sufficient for video chatting with your friends. It is not good enough for creating a technical video. The difference made by recording with a quality microphone is astronomical. Pair that with an audio recording tool like Audacity (which is free, by the way) to edit long pauses and remove static noise, and you’re in business.

5. Craft your voice.

There are so many technical screencasts out there which are dry and hard to watch. One of my favorite videos is You Suck at Photoshop – Distort, Warp, & Layer Effects, where the narrator takes you through using various Adobe Photoshop tools with some profanity and humor. However, not every brand will want a “fun” voice or allow for a large range of creativity.

No one wants to watch a boring video: passion is key. You can write a quality script, but remember when you record the audio to grab your audience. Don’t let them go until the video ends.