Programmers are notorious for their dislike of documenting code. (I'm no exception! Comments in code aren't too bad, but writing documentation for users?!) Nonetheless, we all have to do it, right? I know that in our shop, we need to create "run books" that explain step-by-step how a user is to perform a particular task, such as entering an order or adding a customer.

Written documentation works OK for plain-text screens. But it never works as well as demonstrating the process for the user, where he can see the screens as I'm typing the commands. With GUI software, being able to see the actual screens is even more important. For example, written software that has instructions like "click the doo-hickey that looks like a curly arrow" can be hard to follow.

Therefore, I'm proclaiming that the age of video documentation has officially begun! With video documentation, you can easily create a step-by-step tutorial for your users and show them exactly what the screens look like, and they can watch it anytime. Best of all, it's free!

Wink, Wink, Nudge, Nudge

There are many software packages that you can use to create video documentation. I've settled on a program named Wink by Satish Kumar. Wink is freeware, which means you can download it from the author and use it free of charge. It's available for both Windows and Linux. You can get your copy at the following link:
debugmode.com/wink/

Of course, one disadvantage of freeware is that no support is offered. If you want support, you can go with a commercial product. There's also a commercial alternative named Jing that has been highly recommended by Jon Paris in some of his talks. Jing is available in a free version (served from Jing's servers, with limited features) or a Pro version that requires a subscription. Here's a link to the Jing website:
jingproject.com/

Since I'm too cheap to pay for Jing, and since I want to host documentation from my own website (not to mention System iNetwork's site), I've been using Wink.

What Wink Does

You start Wink and tell it to capture the contents of your PC desktop or the contents of a specific Window on your PC. Then you do your work as normal, and it records your screen, making a recording of what you do. When you tell it that you're done, it brings up an editor where you can edit what you've just done (if necessary) and then render the result as a movie.

The movie is recorded in Adobe's Shockwave Flash (swf) format. That's the same format used by online services such as YouTube and Facebook. Just about every web browser on the planet has Flash installed, so you can put your video on a web page and ask your users to point their browser to the video. The Apache HTTP server available on IBM i will work nicely for this, as will Apache running on another platform, or even Microsoft's IIS. If running a web server isn't practical, you could even put these files on a CD-ROM so that when the CD is inserted, it'll automatically play in the user's browser.

If hosting your own web server is a problem in your shop, try using Jing instead. With Jing, the video is hosted on Jing's site instead of your own.

A Traditional Example

Recently, I used Wink to create some instructions to post in a thread in the System iNetwork forums. There was a question from someone who was new to our platform. The poster was interested in how he could get a list of users on the system and then select an option that would delete a given user and change all objects to be owned by someone else.

The immediate response in the forums was "use the WRKUSRPRF command." But the original poster wasn't familiar enough with the system to understand how WRKUSRPRF solved his problem, and he couldn't visualize the screens.

So I fired up Wink, ran through the process in my 5250 emulator, and created the following video:

If you have trouble viewing the preceding video, click here to view it in its original format.

A few notes about the preceding example:

• If the tutorial goes too fast, the user can always click the "pause" button in the lower-left corner of the video.
• I first recorded the process using Wink.
• Since I didn't have a microphone handy, I couldn't narrate it. So I used Wink's editor to insert those yellow boxes with explanatory text.
• Wink does support audio narration, however.
• As this is a green-screen example, it wouldn't have been difficult to document it on paper with screen shots, but this way was easier for me!

A GUI Example with Audio

I thought the preceding example was pretty neat, and it was easy to make. It took me less than 30 minutes to make, and most of that time was spent trying to figure out how to insert the text boxes.

Because it was a green-screen example, however, I wondered if people reading this article would say, "Why bother? I could do that easily with screen shots and instructions." So I wanted to demonstrate a GUI example that did use sound.

This example is to demonstrate how to upload a picture for an employee into Klement's Sausage Company's employee attendance software. (This is a program that I wrote to keep track of employee attendance, and our HR department wanted to be able to store a picture of employees alongside their attendance record.) Having sound made this process much easier, since I didn't have to try to insert comments into it—I could just record my voice as I did the work. The following took me less than 10 minutes to create:

Granted, this is a very short procedure, but 10 minutes to create documentation that's this easy for the users to follow? It's hard to beat!

Concluding Thoughts

If you work for a consultancy or a software house, you will almost certainly still need to have paper documentation. In that case, having video documentation like this won't save you any time but may still enhance the experience for your clients. They'll enjoy having this as an alternative (and often better) way of learning about your product.

If you're an in-house programmer like me, you might be able to eliminate some of the paper documentation altogether. Video documentation is often easier for the user and is a time-saver for the programmer creating it.

What do you think of this idea? Would you like to see a tutorial explaining how I created these videos? Or an example of how you'd put them on a CD-ROM? Do you think this method of documentation has merit? Post your thoughts as a comment, below!