Using GIFs in Feature Documentation

Introduction

Effective documentation is critical to any software project. I use GIFs to communicate my contributions with co-workers. GIFs can be embedded into most project management applications, making their accessibility seamless in anyone’s workflow. While GIFs cannot replace well-written text completely, they can give the viewer context to enhance understanding.

In this post, I’ll expand on how to create informative documentation GIFs. I’ll use these 3 principles to guide the conversation. At the end, I’ll bring all the principles together in an example.

1. Break Down the Action with Steps
2. Show Only What’s Relevant
3. Orient the Viewer in Time & Space

1). Break Down the Action with Steps

Before you begin working on a documentation GIF, create a set of steps detailing how to use the feature. Follow these steps exactly as you record the demonstration, and add these steps as captions to the GIF as they happen in realtime.

2).  Show Only What’s Relevant

Tightly crop the GIF to only show your subject matter. If you are demonstrating a small desktop application, there is no reason to capture each pixel of your high-resolution monitor. It can be difficult to understand (or even see) the focus point of an uncropped GIF.

Next, tidy up. If you must show your desktop, hide your icons beforehand. If you are demonstrating a feature with a browser, hide the bookmarks bar and any add-on icons. All of these things can be hidden with a few clicks.

3). Orient Your Viewers in Time & Space

The ease of access that makes GIFs so useful does create issues. On a webpage, GIFs do not ask for permission; they pull you into their world immediately whether you are prepared or not. The sudden influx of information can be jarring. Do what you can to make the viewer understand what is happening in your GIF’s universe.

Time

Because GIFs begin playing when a page loads, it’s not always obvious when a GIF starts and ends. To solve for this, add a title slide to the beginning of your demonstration GIF. I would suggest letting this frame run for at least 3 seconds. It’s not important that the viewer can read everything at once, just let it serve as a marker for the beginning of the demo.

There’s no progress bar beneath a GIF. If the viewer comes in a few frames too late, it’s hard to know how much time to wait before the GIF will loop back to the beginning. Add a runtime/progress bar graphic directly on to the GIF. Demo GIFs should be short by nature, but regardless, your viewer will appreciate the assurance that they are not going to waste minutes waiting for a GIF to cycle back.

Space

At times, it can be neccessary to show only a small portion of an application window to demonstrate a feature. Add exposition frames at the beginning to show whereabouts on the application the more detailed frames are occuring. Be sure to draw the viewer’s attention to important section in the exposition frames. This can be done by moving your cursor toward this region or even beginning to perform some action in that area.

Bringing it All Together

As an example of a feature demonstration GIF, I will use a web application I built for a friend’s neuroscience research. The web app stores surgery sessions and recording data from different regions of a mouse brain, layed out as a cartesian plane. The feature in question was the ability to edit data and add more recording data to a surgery session after it was saved. The feature card would have looked something like this:

As a user, I want the ability to change surgery information, add comments, and new data points to the surgery map after I have saved it.

The steps for feature reprduction are:

1. On the home screen, click the map you would like to edit.
2. Click the Edit button in the top left corner of the view map page.
3. Add a new track to the map using the form on the right of the page.
4. Edit the orientation coordinates using the table on the top of the page.
5. Save the map by clicking the Save button in the top left corner of the page.