Creating Videos that Show How to Use an API

Guest Author
Aug. 05 2013, 09:00AM EDT

This guest post comes from Peter Gruenbaum, founder of SDK Bridge. He has worked as an API writer to describe APIs for eCommerce, traffic prediction, electric utilities, mobile phones, and tractors, just to name a few.

The internet is full of videos that teach how to use complex software, like Photoshop or Final Cut Pro. Why not use the same technique for teaching how to use an API? Younger developers, who grew up in the age of these video tutorials, find this format especially useful. These types of videos do not have to have high production costs – they simply require screen capture and voice-over.

However, there are some challenges specific to creating videos about APIs that are different from teaching how to use GUI-based software tools. In particular, creating visually-interesting footage about coding can be tricky. This article describes what kinds of subjects work best with videos, the tools that you can use to create them, as well as suggestions on how to make them visually compelling.

What is best covered in a video tutorial

Videos are not suitable for all types of API information. For example, it’s not effective to use it to convey API reference material, since it’s not an efficient way for developers to get the information that they need. However, it is very useful for two types of subjects: overviews and “How To” topics.

Overviews can contain information about what an API can do, or they can contain architecture information that orients you to how the API works. An example of an overview video is the Introduction to Kinect for Windows Natural User Interface.  (To watch the video, click the image under the “See It” heading.)

How To videos are useful if you there are specific tasks that would be useful for your developers to know how to do. Ideally, you should not only how to do the task, but put it into a context so that developers understand the value of the task. An example of this style of video is Creating a Simple Time-Reporting Tool Based on the Outlook 2010 Calendar. (The video is on the right-hand side, under “See It”.)

Tools

You will need some software tools to create these videos:

Video editing Tool

I highly recommend Camtasia Studio, which is designed specifically for creating screen-capture videos. It makes it easy to capture footage from the screen, apply voice-overs, highlight important areas, and zoom in on parts of the screen where the action is taking place.

Presentation Tool

You’ll sometimes want to display information in addition to the screen capture. Tools like Microsoft PowerPoint work fine for title screens, diagrams, and other information displays. Camtasia Studio even has a PowerPoint plug-in, making it easy to bring PowerPoint slides into your video while adding a voice-over.

Visual Web API Tool

If you are showing how to use a Web API, then you’ll want a tool with a good-looking user interface to make those web requests. My favorite is the Chrome app Postman.

Visual Appeal

The biggest challenge of making videos about APIs is that APIs are text-based, and watching someone type text is about as dull as you can get. When creating your video, you need to make it as visually interesting as possible.  Here are some ideas for how to make calling your API more visually appealing.

Web APIs

Use a visual client, such as Postman, rather than a text-based tool, such as curl. A good visual client will create a nice way to display query parameters and headers, and will format the returned XML and JSON so that it’s clear to read.

SDKs

Make use of the IDE’s GUI as much as possible. For example, instead of hitting F5 to run, click the run button. Set up breakpoints and show the values passed it and returned from your API.

Sample Code

Create some end-to-end sample code that demonstrates what the API can do. First show the sample code, and then dive into the code to show where your API is being called. You can do this for both web APIs and SDKs.

Highlighting

Make use of highlighting to bring attention to where your code is being used. My favorite highlighting tool in Camtasia Studio is the spotlight. For the spotlight effect, you define a rectangle that remains at normal brightness, while everything else on the screen darkens. This very effectively draws the viewer’s attention to that rectangle.

Using the spotlight has one downside, which is that it can only be used in one spot at a time. If you want to highlight more than one rectangle, you need to use a different highlighting tool, such as drawing a red rectangle around the region of interest. Arrows can also be used.

Break Things Up with Presentation Slides

We’ve all know how dull it can be to watch PowerPoint presentations that are an endless series of bullet-point slides. However, bullet-point slides can be a simple, effective way to break up your screen captures. Use animations to have each bullet point fade in, and time them to work with the voice over. But add bullet points sparingly, so that it doesn’t end up looking like one of those endless PowerPoint presentations.

PowerPoint’s simple animations can be used to create some good visual effects as well. For example, in the Developer’s Guide to the Excel Object 2010 Application Object video, at the point 1:10 (that is, 1 minute, 10 seconds into the video), you can see how animations are used to illustrate using an object property hierarchy.

Conclusions

Videos can get developers up to speed quickly on using your API. To make your videos effective, follow these tips:

  • Use videos for overviews and explaining how to do common tasks
  • Use tools like Camtasia Studio for easy screen capture and voice-overs
  • Make your video visually appealing by using visual tools, sample code and highlighting
  • Break up screen capture footage with presentation slides
Guest Author

Comments

Comments(1)

Peter,

Thank you so much for posting this piece. I am a technical writer who has updated a few API manuals and always find myself wishing I had the time to do a short API. This is an invaluable resource and I thank you. I'm inspired to create one now!

Back a few years when I was contracting after enduring a long layoff period, I found your website and guidance invaluable when approaching contracting positions. I hope your good karma comes to you one hundred fold for all the support and information you've shared.

Bobbi