Storyboards for video design and review

I’ve just created two short instructional videos, introducing specific aspects of our APIs to developers. I used a storyboard as a way of outlining the video content, illustrating my ideas about the flow of the video, and requesting a review from my colleagues.

A colleague, Rachel, introduced me to the idea of storyboarding a while ago. This is the first time I’ve tried it.

What a storyboard looks like

This is what the storyboard looked like when I sent it out for initial review comments:

My first storyboard

To get started, I looked at the examples Rachel had given me of her own storyboards, remembering her very useful comments about how she used them. Then I looked online to see what other people are doing. I found two examples that gave me more good ideas on how to represent my video design in a storyboard:

• Storyboards, from the Advanced Computing Center for the Arts and Design. I like the Hunting Sequence from the Jane Animation Project.
• Storyboarding, from the UC Berkeley Graduate School of Journalism. The sketches at the bottom of the page are appealing, and show how different formats of storyboard are useful in different situations.

The design of my storyboard is a conglomeration of ideas generated by my colleagues examples and the two sources above. I shared my storyboard template with members of my team, and suggested they may like to use something similar when designing videos. They like the idea, and each person adapted the template to suit them. This approach works surprisingly well.

What a storyboard is good for

For me, the primary goal of a storyboard is to share an easily-absorbed way of representing the flow of the video.

This is what I wrote at the top of my first storyboard:

This storyboard is a precursor to a script. It’s an illustrative way of outlining the video before we start in-depth development of code and script. Note: All visuals are just mockups to give some idea of what’s happening, and are not intended to be the real thing.

Building out the storyboard

As time passed, I fleshed out the script on the storyboard, replacing the outlined content with the words I was planning to say during the presentation. So the storyboard evolved continually during the scripting of the video, the flow design, and the planning of the visual aspects such as screenshots, demonstrations and annotations.

A number of colleagues responded to my requests for review. After a few revisions, my script was ready to move to a separate document for final tweaking and practice runs. This is what the storyboard looked like at that point:

The storyboard ready to be transformed into a script

The resulting video

This is the very first instructional video that I’ve ever presented! (Apart from videos shot during conference presentations.) It’s short by design. The target audience is developers who are using the Google Maps Android API to include maps in their Android apps.

Producing the video

I could write an entire blog post about the process of filming the video. So for now, I’ll just show you a couple of photos of the video production studio.

The first photo shows me sitting in the hot seat, with the green screen behind me. In the foreground are the two video production screens, with ATEM Television Studio (the input stream switcher) on the right and Wirecast (which we used to define the video format and control the flow) on the left.

In the hot seat in the video production studio

The second photo is a panoramic view from the hot seat, showing all the lights that glare down at you. The production centre in the middle at the back.

The view from the hot seat

Conclusion

A storyboard is a good tool for solidifying my own ideas about the video, showing them to others, and conducting a collaborative review.

I’d love to hear your ideas about storyboarding, the format of the storyboards you use, and how you find them useful (or not). 🙂

How to write sample code

Technical writers often need to create sample code, to illustrate the primary use case of an API or developer tool, and to help developers get started quickly in the use of the API or tool. Here are some tips on how to go about creating that code. I’ve jotted down everything I can think of. If you have more tips to add, please do. 🙂

I recently published a set of documentation on a utility library created by Chris Broadfoot, a Google developer programs engineer. The utility library is an adjunct to the Google Maps Android API. The documentation includes an overview of all the utilities in the library, a setup guide, and an in-depth guide to one of the utilities. (I’ll document more of the utilities as time goes on.) As part of the guide to the marker clustering utility, I created some sample code that illustrates the most basic usage of the utility and gets developers up and running fast.

Quick introduction to the API and the utility library

The Google Maps Android API is for developers who want to add a map to their Android apps. The API draws its data from the Google Maps database, handles the displaying of the map, and responds to gestures made by the user, such as zooming in and out of the map. You can also call API methods to add markers, rectangles and other polygons, segmented lines (called polylines), images (called ground overlays) and replacement map tiles (called tile overlays). It’s all in the API documentation.

The utility library is an extra set of code that developers can include in their Android apps. It includes a number of useful features that extend the base API. One of those features is “marker clustering”. The full list of features is in the utility library documentation.

The marker clustering utility

The sample code illustrates the marker clustering utility in Chris’s utility library. So before diving into the code, you be asking:

What’s “marker clustering”?

Let’s assume you have a map with a large number of markers. (Typically on a Google Map, a marker is one of those orange pointy droplets that marks a place on the map.) If you display all the markers at once and individually, the map looks ugly and is hard to grok, especially when the map is zoomed out and many markers are concentrated in a small area. One solution is to group neighbouring markers together into a single marker icon (a “cluster”) and then split them into individual marker icons when the user zooms out or clicks on the cluster icon. That’s what Chris‘s marker clustering utility does.

What does marker clustering look like? See the screenshots in the documentation.

Developers can implement the classes Chris has created and customise the appearance and behaviour of the clusters. The utility library also includes a demo app, containing sample implementations of the utilities.

The sample code

The best way to describe a code library is to provide sample code. I created a simple marker clustering example, based on the demo app. Take a look at the sample code in the documentation section on adding a simple marker clusterer.

Now compare it to the code in the demo app that’s part of the utility library: ClusteringDemoActivity.java

The differences, in a nutshell:

• The sample code doesn’t show any of the “plumbing”, such as the library import statements.
• The sample code does include a listing of both the primary method that does the clustering (called “setUpClusterer()“) and a class that’s important for developers to understand (“public class MyItem implements ClusterItem“).
• Instead of reading input from a file, the sample code includes a method called “addItems()” to set up some sample data directly from within the code.
• I’ve added plentiful comments to the sample code, explaining the bits that are specific to marker clustering or the sample itself.

In summary, the sample code provides all the developer needs to get a simple marker clusterer working, just by copying and pasting the code into an existing Android project.

How to write sample code

While writing the sample code, a thought struck me:

Hey, it’s actually quite an interesting process writing sample code. I’ll blog about what I’m doing here, and see what other technical writers have to say about it. 🙂

First, a stab at defining the goals for the sample code:

• Get the developer up and running as quickly as possible.
• Be suitable for copying and pasting.
• Work (do what it’s meant to do) when dropped into a development project.
• Be as simple as clear as possible.
• Provide information that is not easy to find by reading the code.
• Illustrate the primary, basic use case of the API or tool.

And here are my jottings on how to go about creating a useful code sample:

• Find out what the primary and simplest use case is. That is what your code should illustrate. Talk to the engineers and product managers, read the requirements or design document, read the code comments.
• Find out what you can safely assume about your audience. Can you assume they are familiar with the technology you’re working with (in my case, Java and Android development)? Do you know which development tools they are using?
• Find some “real” code that does something similar to what you need. Perhaps a similar function or a working implementation that’s too complex for your needs.
• Simplify it. Make names more meaningful. Remove functionality that’s unique to your environment or that adds super-duper but superfluous features. Remove plumbing such as import statements and all but the essential error handling.
• Put your into a framework and test it. The framework should be one that your audience will be using. In my case, that’s an Android development project.
• Take screenshots of the code in action. They’re often useful to give people an idea of the goal of the sample code, and of what the API or tool can do.
• Get the code reviewed.
• Include it in the doc.
• If possible, put the code in a source repository and hook it up to some automated tests, to help ensure it will remain current.
• As far as possible, have all the necessary code in one piece, so that people can copy and paste easily. This may mean moving stuff around.
• Add code comments. Engineers often add technical comments to the code, but don’t include an introduction or conceptual overview of what’s going on. And our target audience, developers, will often read code comments where they don’t read other docs. So code comments are a great medium for technical communication!

Perhaps the most important thing to do is to see yourself as the advocate for or representative of those developers who need to use the API or tool you’re illustrating. Think what questions they would ask if they had access to the people and tools that you do, and put the answers into the documentation and sample code.

Conclusion

To do this job, tech writers need a certain level of coding knowledge, and also a good understanding of what a developer needs to get started. The sample code provides a stepping stone between the conceptual overviews and the complex implementations.

Well, that’s all I can think of. What have I forgotten? 🙂