By Ingrid Higgins
My technical documentation team recently faced a challenge: Communicate a technically complex, system-wide feature with multiple scenarios in an easy-to-understand way. Our solution was to embed Flash illustrations and animations in a PDF manual. This case study describes the planning, beta testing, and lessons learned when we decided to complement technical information with interactive Flash content.
A Picture Is Worth …
During the design phase for a technical manual that described a new feature within private radio networks, we determined that many scenarios would need to be defined. Unlike manuals that cover a single piece of hardware or a particular software application, this manual needed to document a system-wide feature. We imagined page after page of if/then tables and text to define numerous scenarios and different system architectures.
During brainstorming sessions with our system specialist, we questioned how we could best present the content. We wanted to be able to compare and contrast various architectures, describe contingency and dependency scenarios (for example, what happens at points B and C when A is triggered), explain scalability, and describe optional implementations within different types of infrastructure. Additionally, we knew that the manual was going to be used as the basis for an e-learning course and, possibly, some internal training, so anything we developed that could be multipurposed would be a bonus.
In conjunction with a green initiative to provide manuals electronically in Portable Document Format (PDF), we decided to approach the challenge outside of the printed manual mindset. Would Flash drawings or animations illustrate our scenarios and content better than text? Is a picture indeed worth a thousand words?
We decided to use Flash embedded in a PDF as our solution. FlashPlayer ubiquity in our U.S. target audience is at 99 percent (see www.adobe.com/products/player_census/flashplayer/version_penetration.html), so we felt assured that any user of our documentation would have the ability to view the Shockwave Flash files (SWFs) we created. We knew that laptops or desktop computers were being used by our audience and that Adobe Reader would be installed.
Our plan was to have each Flash movie cover a particular segment of network architecture. This approach allowed us to show iterations of various network elements. Through simple button actions, comparisons between a series of illustrations could be made, which allowed the reader to switch between two, three, or more views. In a few instances, Flash animations would be created to further explain “what happens when” situations. Accompanying text would be written to provide detailed information for each segment. Since this had never been done by our group before, we created some initial interactive drawings and did a beta test on several users. We were now faced with our second challenge: Convincing the traditionalists.
The Beta Test and What We Learned
For our beta test, we created a PDF that contained one chapter of text. We complemented the textual content with the drawings in the SWFs. Within the chapter, we embedded our sample Flash files and included instructions for how to launch the SWFs. Then we set up test sessions with internal representatives of our intended audience. Here’s what we learned.
The push-back from traditionalists was strong. People who are used to holding a printed manual, who are more comfortable turning pages rather than scrolling screens, were unhappy that Flash is not printable. (Actually, the PDF we created can be printed, but in place of the Flash SWFs, a JPG is displayed.) The response from most users we tested ranged from pleasant surprise to outright delight when the interactivity of the embedded SWFs was discovered.
Lesson 1: You can’t please everybody. However, it is a good idea to get consensus from your stakeholders when you intend to produce a manual with embedded Flash. Even better, find a champion who embraces the idea as much as you do.
Our intention was to have the written text complement the SWFs; the SWFs would provide the visual overview and the text would provide the full details. Although we attempted to marry the text in the chapter with the illustrations, we noticed that many people jumped to the Flash drawings before they read any of the text. One user suggested we drop the text altogether and have all the content within the illustrations. When development resumed after the beta test, we revised the Flash content to include additional descriptive text within each movie.
Lesson 2: Users can be text readers or graphics readers or a little of both. Enough content needs to be included in both the text and the Flash illustrations to pass information to either type of user. (It is important to mention here that translation was not a requirement for this manual, so we were safe in adding text to our Flash content. If a manual is going to be translated, keep the SWF content to illustrations and animations only.)
We knew that our intended audience was comfortable interacting with Flash on web pages, but we were providing Flash in a “new” space (a PDF) where few people were accustomed to seeing it. During a preliminary test, some people assumed that the embedded SWFs were graphics, so we provided text in the chapter introduction alerting the user that the “graphics” were actually Flash SWFs. We also added instructions that explained how to launch the FlashPlayer to display the interactive content.
During the beta test, we watched most users skip the introduction altogether. Even if we moved the Flash launch instructions to the preceding paragraph, most users skimmed past them.
Lesson 3: If you embed Flash in a PDF, you have to provide the launch instructions within the SWF, not in an introduction or even in the preceding paragraph where it is easily—and usually—ignored. We initially designed the SWF placeholder images (or posters, in Adobe Acrobat Pro terminology) to be clear, printable JPGs since we knew our traditionalists would be printing the PDF. But this caused confusion because it looked too much like a regular graphic. We revised the look of the placeholders to differentiate the SWF files from static graphics. Our final design included a click-anywhere overlay with user instructions for starting the Flash movie.
Some of our Flash movies were simply a series of comparable system drawings selectable by the user. We wanted a user to be able to compare and contrast system A with system B with system C and switch between views to see the differences. We also provided some iterative drawings, for example system A plus system B with optional system C. While we thought clickable options like “Show me Architecture A” and “Show me Architecture B” were intuitive, some users needed to be told to click an option to view that illustration.
Lesson 4: Don’t presume anything is intuitive. Provide user instructions to the Flash content, even if it’s only a short sentence like “Click an option from the list.”
Other Flash movies we developed were animations. We spent a good amount of time ensuring that the speed of the playback was comfortable, neither too fast nor too slow. What we learned is that there are users who do not want to watch even four seconds of animation and would prefer to see the end result, not how to get there.
Lesson 5: Include a skip button to take the user to the end of an animation. And while you’re at it, include a Replay button, too. For longer animations, a play/rewind/forward/pause control is advisable.
We couldn’t think of why someone would want to print from a FlashPlayer, but a few of our beta testers tried. If a user tries to print embedded Flash content in a PDF, they should choose “Selection” to print the current frame of the movie. If the print Page Range is set to “All,” every frame of the SWF will print, which in some cases could be hundreds of pages!
Lesson 6: Because there’s always somebody who will try to print from the FlashPlayer, include a warning somewhere in your text for users to choose “Selection” to print a frame.
Our beta testing provided us with good user feedback and lots of usability lessons. We went back to the drawing board and implemented just about every suggestion we received from our target audience. The door is still open, and we continue to garner feedback from other audiences as well.
The Return on Investment
From conceptual design to final PDF, this project spanned several months. The development time was not much longer than any content developer/graphic designer would spend per page for a technical manual. Most of the additional time we spent was on the beta testing in order to “do it right” the first time.
Besides achieving the wow factor of introducing something new to our technical documentation, our development time was well spent in other ways. SWFs can be embedded into PowerPoint, displayed on a web page, or imported into various e-learning software applications. While the level of effort to create the drawings and animations seemed high at the outset, the SWF files were made available for use by in-house trainers, engineers, and marketing professionals. The companion e-learning course reused every one of the SWFs.
Embedding Flash into PDFs takes advantage of the fact that many technical manuals are now being delivered in electronic form. Besides laptop and desktop computers, tablets and eReaders are changing the way manuals are being distributed and technical information is being accessed. Manuals and user guides no longer need to be printed, bound, and shipped. Instead, PDFs can be generated and made available for downloading. Besides being a green alternative to printed documentation, PDFs allow technical communicators to take advantage of the robust features available in this electronic format.
Acknowledgement: My outstanding coworkers, Janet Castelli and Alex Torres.
Ingrid Higgins (ingrid.higgins@motorola.com) is a staff media developer for Motorola’s Enterprise Mobility Solutions business in Schaumburg, Illinois. She has received STC Distinguished, Excellence, and Merit Awards in online communication.
