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.
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”.)
You will need some software tools to create these videos:
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.
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.
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.
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.
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.
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.
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.
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.
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.
Videos can get developers up to speed quickly on using your API. To make your videos effective, follow these tips: