Incorporating Video into Technical Information

March 18, 2011

I’ve earned sort of a cool reputation among my colleagues as “Patty Spielberg” for all the work I’ve done on our product demo videos.  (They’re posted up on YouTube if you’d like to check them out.)

As cool as this is, there are also some drawbacks to it, tops on the list being I DO HAVE OTHER WORK TO DO!  Video production has a tendency to suffer Scope Creep, so here are some tips on managing this effort in case you find yourself in my predicament.

Invite Murphy

Don’t even try to prevent things from going wrong; they will.  It’s a given. The best prevention is to have contingencies in place.  We’re using Adobe Captivate to produce our videos, but not all writers have a license and running it from a server is prohibited by the license terms.  So, we installed it on a lab machine we can all use. Sort of like a kiosk. This is the backup plan in case the version I have on my laptop fails. I also have a backup mic in case the primary mic fails.

Set up the Environment

Documenting software without a functional version to play with is challenging, certainly not a best practice, but nevertheless, doable. But producing videos without a functional version is just not possible.  For this reason, I defer video production to as late in the development cycle as possible – usually, right before beta begins. Of course, waiting this long risks meeting the project schedule, so you’ll have to weigh those risks over the potential benefits, such as recording from a stable and (hopefully) bug-free software build.

You should also have a thorough understanding of the task you plan to record. I’m doing product videos for all of my team’s products, even those I’m not documenting. Because I’m unfamiliar with the interface and the design intention, I frequently cannot perform a task without expert guidance.  When you plan a video production project, remember to plan for some practice time. Familiarize yourself with all the menu selections and values that should be entered in selected fields so that you can perform the entire task without error at recording time.

Measure Twice, Cut Once

I like to work with a script for this reason. If I am not the technical writer assigned to the product I must video, my first step is to study the tech writer’s content. Much like peer editing, I often discover ambiguity in procedures as written by lending fresh eyeballs. I use the written procedure to develop a script. My scripts are Word tables with two columns: one for a description of the on-screen action including what screen should be displayed, what menu to select, what values to enter.  In the second column, I add the voiceover I plan to record on that screen.

I route all video scripts for review and approval within the product team. Members help me use the best terms (“Use ‘recover’ not ‘restore’), identify inaccuracies, offer suggestions for the features they want me to emphasize.  Script approval before the work begins is a critical time-saver. Once a video has been recorded and sync’d, changing problems after-the-fact requires an almost total re-do.

A Lot of Cooks in the Kitchen

As our video demos gained traction, they’ve evolved according to various corporate directives. For example, my first attempts merely had our company logo. Today, the Marketing team asks that I use a specific PowerPoint template for branding purposes, and a Flash fanfare opening sequence. There are also copyright and legal disclaimers I must use.

The Localization team is busy working on a way to streamline the translation process without having to completely record a video in each language. Depending on the size of your company, there may be additional teams with a stake in each video, i.e., Education, Pre-Sales, etc.  Track each requirement carefully and be sure to estimate it in future project plans.

Ask for Help

This aligns with that pest, Murphy, and his annoying tendency to foul things up. Since we’re deferring video production to as late in the development cycle as possible, time is naturally not to be wasted. Yet, like most people, I typically have more than one task on my daily To-Do list and those things cannot always wait until a video is done.  It’s okay to ask for help. During my latest video production efforts, I had a product with no name, an unstable build, a laptop that went on strike, a personal situation that required three days off and an injury that caused some discomfort to contend with.

While my laptop was being repaired, I worked on the kiosk. I revised the script so that the product is named as infrequently as possible, used photo-editing software to change the screens where instability was visible and took frequent breaks to help manage my pain. My colleagues helped record software tasks and prepared one of my other projects for a localization turnover while I locked myself in an empty office to record the voiceover. I could not have succeeded without the assist.

Give Them Food or Teach Them to Fish

Finally, I suggest documenting your own procedures as you fine-tune them and then holding impromptu training sessions with your colleagues. I did just this last month, so when I asked my coworkers to record tasks using Captivate, they were capable of doing so with minimal guidance from me. Not everyone is comfortable recording narration, though. Honestly, I’m STILL not comfortable with it myself.

That’s pretty much it. As writers emerge from their comfort zones and begin learning multimedia technologies like screen capture and video production, this will become as easy as typing. Tell me, are you incorporating new media into your documentation projects? I’d like to hear about it.



  1. Thank you so much for this article.

    Currently, I am tasked with creating small videos to embed into our help. They have to be small, easy to produce and not impact the project schedule. Oh, and we have no budget for it. Stop me if this sounds familiar 😉

    I’m curious to know how you like Captivate as I am currently shopping tools to create these videos.

    Again, thank you!

  2. Hi, Matthew,

    I’ve used only Captivate and Camtasia so far and I lean toward Captivate because it captures everything in a PowerPoint-like way, making it easy to edit because it’s so intuitive. I have to remove IP addresses, User IDs, and other security info from every screen, so this is great. Camtasia puts everything in one big timeline. I don’t know how to edit that, though I figure it’s possible.

    FYI, I’m still using Cap 4 and hear 5.0 is awesome! You can download it for free for a 30 day trial. I’d recommend that. It’s fully functional, so you can truly test drive it.

    Good luck. I hope this helps.

    • Patty,

      You rock. Thank you. Currently, I have an old 2.0 captivate license and would love to upgrade to 5.0. We’ll see how that goes.

      I too will have the same url issue, so it’s good to know Captivate handles that well.

      I also look forward to following you on twitter.

      Thank you,

      • My pleasure! Good luck.

  3. […] Incorporating video into technical information […]

  4. This makes handling the project much easier and much more visually oriented than in other applications. It is easy to position the effect to the exact frames without splicing the video. It is easy to move the effects or resize them in timeline or even copy and paste them without touching the video tracks!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: