You will have a chance to cast a vote for the projects that provided you with the most inspiration. The 2012 Most Innovative Project Award will be presented at the closing session of the conference.

Wednesday • 10:50 am - 1:05 pm

The Peer Showcase features a variety of blue ribbon user assistance solutions presented to you in an informal setting by the developers themselves. You'll have plenty of time to pick the brains of the Showcase presenters to find out how you can construct similar projects on your own.

If you feel you have a project you would like to contribute to the Showcase, please contact Joe Welinske (joewe *at* writersua.com).

2012 Peer Showcase Roster

Click on a title below to view a project description. Additional projects will be added as the conference approaches.

• Using FileMaker Pro to Manage the Indexing of Videos
  Jan Wright, Wright Information Indexing Services
• Using Doxgen's Doxywizard to Generate Documentation
  Rachel Samuel, Accusoft Pegasus
• Creating Flash Rollover Images with Captivate and Snagit
  Fer O'Neil, ESET, North America
• Using a DITA Framework with Heavy Text Reuse to Replace Thousands of Framemaker Files
  Don Lammers, Xilinx Inc.
• Using Author-it Live and Author-it Extend to Support a Dynamic Authoring Environment for 30 Subject Matter Experts
  Paul Pehrson, The Church of Jesus Christ of Latter-day Saints
• Converting Conference Presentation Materials into Help System Resources
  Tim Morris, ECi OMD
• Producing High Quality PDFs from DITA using FrameMaker
  Scott Prentice, Leximation, Inc.
• Using Conditional Builds and Multiple TOCs in RoboHelp to Create Online Help, a Training Leader’s Guide and a Training Participant’s Manual
  Beth Gerber, Lightext
• Using RoboSource Control and Perforce with a WebHelp System
  Mark Whisler, Altera

---

Using FileMaker Pro to Manage the Indexing of Videos

Jan Wright, Wright Information Indexing Services • Sandia Park, NM

Indexing the contents of videos and DVDs pose a unique challenge, especially if a company cannot afford a half-million-dollar content management system. If a company is also short on internal programming resources, and is responding nimbly to its marketplace in this economy, it may not have time to divert staff to developing open-source content management either: the staff are busy creating content and selling it! If you are producing a lot of video materials, and need to keep track of both administrative metadata and content metadata, a database can help serve both needs. Two years ago, a books/multi-media/product and web-sales content company decided that they needed to: Keep track of the contents of the large numbers of DVDs they were creating and selling Locate and repurpose the materials as needed Track all the talent, sponsors, products, and techniques demonstrated Trace video content to web-sold products or free give-aways Find video segments to advertise DVDs and other web-store products After pricing and consulting on commercial content management, and pricing the costs of CMS development in-house, the company decided to: Postpone a content management project Focus their staff on the revenue-creation:creating/selling content Make content data available internally. We searched for reasonably-priced software: Lots of packages will catalog DVD administrative metadata None addressed the content metadata A database needed to be the solution After working with several off-the shelf database packages, we found that the best way to both index the data and prepare for an eventual content management system would be to create a flat file database that could be marked up in XML, and imported into any future content system. Access and Excel both failed: too many fields on each DVD. FileMaker Pro is both Mac and PC compatible FileMaker Pro could handle the fields required FileMaker Pro's macro capacities output a print-like index, and customized reports listing personnel, techniques, sponsors, and other critical data. The next steps were to develop a record structure to handle a core set of metadata tracking the critical pieces of the content: Adaptation of the Dublin core record set Company-critical fields Content indexing fields Fields for handling video on the web and future re-use Lessons learned: FileMaker's easily-built reporting and macro-builders have been of enormous help in producing needed reports on the fly. Vocabulary control has been difficult, but we are able to export to Cindex, an indexing program, convert to alphabetical form, see vocabulary mismatches and correct them in the database. DVD timecodes can really vary: we came up with best practices for dealing with varying systems. The company is now working on implementing the database for internal use, and we have entered over three hundred videos, representing over 600 hours of content, with many more to come as the company puts out more. The single interface now is for record entry, but next steps will include building an internal search interface for staff. The introduction of a FileMaker iPad app will increase its eventual use within the company. A complete controlled vocabulary will be ready for taxonomy use when content management does come to the company. Jan Wright is an indexer and taxonomist who has been working with documentation since 1991, specializing in help indexing, single sourcing, embedded indexing, tagging, metadata, taxonomies and technical subject matter. Her client list includes Autodesk, Microsoft, Visio, Apple, and other companies. In 2009, she earned the ASI/H.W. Wilson Award for Excellence in Indexing for her index to Real World Adobe InDesign CS3, by Olav Martin Kvern and David Blatner, the first time the award had been presented to a technical manual. Last year, she created the first "virtual coffee shop" for indexers, the Indexers Network at indexing.ning.com. She teaches basic indexing for UC Berkeley, and has a Masters degree in Library Science. Her website, www.wrightinformation.com, exhibits a variety of indexing and tagging techniques.






---

Using Doxgen's Doxywizard to Generate Documentation

Rachel Samuel, Accusoft Pegasus • Tampa, FL

I used Doxygen to create online help for our product, ImageGear for Java. ImageGear® for Java is the most advanced way to create, control, and deliver more secure, high-quality imaging applications. Using ImageGear, you can easily add powerful imaging capability to your applications. ImageGear supports all of the most commonly used graphics file formats and many more, providing complete compatibility when developing Java solutions across multiple platforms. Working with configuration files for a help project was a first for me. After creating the help project, I noticed a wizard, Doxywizard. I definitely preferred the GUI. I could change the color theme, and then went a step further to tweak it to add additional customization, like changing the color of the highlight on the active/selected tab, changing the fonts, eliminating unwanted tabs from the main page layout, etc., to create a custom template that suited our company colors and matched the look and feel of our other online help. Another challenge was working around the fact that the authored content did not have a comprehensive ToC. I solved this by offering linked bullet lists of topics in each main/folder level topic. And, since authored content is not included in a project file as in most HATs, topics have to be authored separately in .dox files and stored in a separate folder. Thanks to those who’d posted questions on the forums and those who answered them. Armed with ideas, suggestions, feedback, and my trial and error techniques, I created a solution that suited our requirements. Rachel Samuel has been in the field of technical communication and training for ten years and has written documentation and help for the pharmaceutical and healthcare industries. She is a Technical Writer with Accusoft Pegasus, which is the largest single source provider of imaging software development kits (SDKs) and image viewers, and caters to various industries. She creates the API, general, and sample application help for the Accusoft components.






---

Creating Flash Rollover Images with Captivate and Snagit

Fer O'Neil, ESET, North America • Vista, CA

This project will show how to create a Flash (SWF) image that incorporates descriptive or ancillary information into the image as rollover images (or rollover captions) for use in HTML web pages (online documentation). The software used is Adobe Captivate, Adobe Flash, and a screen capture utility (Snagit). The result can be previewed using Adobe Dreamweaver and uploaded as HTML for the web, as a PDF, or any other documentation deliverable. There are several reasons why using a Flash image is preferred to a standard (static) image. For instance, adding Flash reduces the amount of text on the page and creates the opportunity for the user to interact with the document—effectively allowing the user to 'choose' what he or she wants to or needs to see. Knowing when to use multimedia is important because when a 'hidden' pop-up or rollover is used, there is a risk of the user not seeing the information. For this reason, Flash rollovers should only be used when the information is not essential to the procedure. Meeting the balance between presenting information to an increasingly visual audience and supplying the technical information needed is a current challenge of producers of Web-based Help. Additionally, when to use multimedia comes from knowing what documentation is appropriate for your audience. This information is found through feedback channels and user analysis to determine the best method to present information. With that in mind, this project will discuss the analytics of support documentation, and other user-facing documents that employ rich media elements, and how incorporating user feedback affects the user assistance design and ultimately decreases support cases. My name is Fer O'Neil and I am a Technical Writer for a security software company. Since I began studying for my Masters of Arts, English (Technical Communication concentration), I have been exposed to new theories and practices in UX and UA and have the opportunity to develop and use these new methods of software assistance in the documentation I create.






---

Using a DITA Framework with Heavy Text Reuse to Replace Thousands of Framemaker Files

Don Lammers, Xilinx Inc. • Longmont, CO

The Xilinx Unified Libraries Guides were 17 component libraries guides created from about 6,000 Framemaker files. Although information for individual components was identical across multiple guides, each guide had its own source. With only one writer, the collection was on a 3 year update schedule. We reorganized the collection to use a single DITA file per component, with content references between components and conditional text where necessary, reducing the file count to about 900, and the total text to maintain by an estimated 85%. Now changes made to any component are reflected in all of the guides containing the component, which increases consistency and accuracy. We deliver an updated collection with software releases every three months. The collection still has 17 guides but has expanded to about 1200 source files, and most content for new components can now be directly extracted from the build. The process includes PERL scripts for data extraction and Visual Basic programs that create category reference pages and ditamaps, and insert code templates into the source files. We now generate PDF and HTML output weekly. The PlanAhead Tcl Guide integrates information in the code ("short" help), with "extended" help authored by engineers and service personnel using only DITA "reference" topics, and a limited set of DITA tags to make training new contributors easier. We needed to provide additional explanation and examples to information included in the code, and produce a PDF with all of the information for each command, and publish the additional information back into the software. An internal-only HTML deliverable including both customer-visible and hidden Tcl commands was added later. Processing is with a combination of Tcl, UNIX scripting, and Visual Basic.NET. Once the information is authored in DITA, the aggregation, composition, and publishing are completely automated. Most of the contributors use Serna Free to edit DITA because it is free and fairly easy to set up. Don Lammers is a technical writer and programmer working for Xilinx Inc. in Longmont, Colorado. He creates and maintains specializations and style sheets for documents authored in DITA, as well as internal software that bridges authoring environments with the build systems. Current major projects revolve mostly around automating the production of reference documents including component references (the Xilinx Unified Libraries Guides) and a Tcl command reference.






---

Using Author-it Live and Author-it Extend to Support a Dynamic Authoring Environment for 30 Subject Matter Experts

Paul Pehrson, The Church of Jesus Christ of Latter-day Saints • Herriman, UT

We are implementing new software for our global supply chain, and our team is responsible for creating documentation that will be used in warehouses and distribution centers around the world. Our technical writing team doesn't have the technical knowledge of the supply chain tool, so we are working with content experts (who are not writing experts) in several divisions. We have about 30 SMEs who create the actual content, and we help them ensure it meets our content model and style requirements. We are using Author-it for this project. Initially our SMEs were writing documents in Word which we continually imported into Author-it to create our outputs. Now we have installed Author-it Live and our SMEs do all their writing and editing in the Author-it Live environment. We use a feature in Author-it called "release states" to enforce a review cycle for all completed topics. We use Author-it Reviewer to allow other experts to review the documents and track suggested changes. We use Author-it Extend to maximize the content-reuse options to minimize our translation costs and ensure consistency across the product. Using Author-it, we allow up to 15 simultaneous users access to write, update, and manage their documents. We ensure a proper review by enforcing workflow. We are able to manage user rights so groups (or individuals) only have access to those folders they need for their work (protecting confidential projects that may also exist in the same database). Author-it Live gives our SMEs an easy-to-use writing and editing interface which minimizes the training we had to do to get them up and running. Since Live is a web-based tool, our authors can write from any location on any computer they have access to. Using Author-it, we have worked with our SMEs to create over 700 topics in a way that is easy for them to understand, even for those who are less technical. Paul is a senior technical writer for The Church of Jesus Christ of Latter-day Saints. He has been doing technical documentation for eleven years doing both hardware and software docs. He is active in the tech/comm community, serving as President of Utah's STC chapter and serving on the STC Community Affairs Committee. He is a certified Madcap Advanced Developer, a Flare trainer. He has been using Author-it for enterprise content development and management for about a year.






---

Converting Conference Presentation Materials into Help System Resources

Tim Morris, ECi OMD • Jefferson City, MO

For its 2011 Connect Conference, ECi's technical writers assisted presenters with creating each presentation by updating a company-branded PowerPoint template, importing the template into Captivate 5, and then adding recordings-where applicable-of ECi software offerings. Twenty-one conference presentations featured ECi OMD software, which enables users to perform more than 1500 business application functions on Windows, Unix, and Linux platforms. Following the conference, ECi OMD converted these conference presentation materials-designed by company experts and presented in a tutorial format that includes how-to software recordings-into help system resources with minimal additional effort, and integrated these resources with ECi OMD software's online help systems. This peer showcase will highlight: What we learned from the PowerPoint-to-Captivate conversion process: PowerPoint effects convert well; add them before and/or after the conversion. Some images convert well, some lose drop shadow effects, and some are not converted; add images directly to Captivate after the conversion for best image quality. Numbered and bulleted lists sometimes lose paragraph indents. Numbers above 9 are converted to alphabetic characters. Review list formatting after the conversion. What we learned about adding recordings: Unchecking the Advanced Project Compression feature reduces compression artifacts. Establishing best cursor practices (e.g., don't position cursor so that it hides text when clicking buttons/links) and understanding available cursor options (e.g., ability to change cursor image, reposition cursor, select double-clicking effect) before starting a recording saves time during and after the recording process. When recording remotely across a network, the last action is sometimes not recorded. Include an extra screen click as the last action; it can be edited out if it is not lost. How we converted from the "conference" to the "help system" format: Opening and closing conference session slides were removed. A hyperlinked TOC was added to assist with finding and navigating to specific topics. How we benefitted by re-using conference materials as help system resources: We saved time and money by re-using existing content. Users can access these resources 24/7. Users can control playback speed. A technical writer for eleven years at business software company ECi OMD in Jefferson City, MO, I work on user-assistance systems, write software programs, develop a U/SQL universal data dictionary (.udd), teach webinars, and answer support calls. During the previous fourteen years, I taught college-level composition, developmental reading, and study skills classes at Missouri State University, Rollins College in Florida, and Truman State University.






---

Producing High Quality PDFs from DITA using FrameMaker

Scott Prentice, Leximation, Inc. • San Rafael, CA

As people move to DITA, they are told that they will need to accept a lower level of quality from their PDF output. As a FrameMaker plugin developer I didn't see any reason that this would need to be true. The common method for generating PDFs from DITA is to use an XSL-FO based process. XSL-FO is an Open Source format, which is often popular because it's "free", but it does require a very specialized development effort to produce even the most basic of layouts. Achieving the same level of formatting that you're used to with unstructured FrameMaker can be very complicated (expensive) or impossible. There are definitely situations where XSL-FO is the right choice, but for most publications, you'll spend less money and get better quality output from FrameMaker. You can use the default process in FrameMaker 8, 9, or 10 to generate a FM book from a DITA map, then manually apply properties and templates to the book and components, then save to PDF. This will result in good looking output, but is tedious and error prone. I developed a plugin called DITA-FMx that allows you to predefine the book-build process so you can get a PDF-ready book from a DITA map in one step. In addition to adding any generated lists (TOC, Index, etc), setting up the pagination and numbering, and applying possibly unique templates to each book component, DITA-FMx also lets you add unstructured FM files to the book (typically a hand-crafted title page) as well as running additional scripts (FrameScript, ExtendScript, or FDK clients) to perform necessary pagination and cleanup that would traditionally be done by hand. This book-build process can also import metadata from the map (both attribute and element data) into the book components as variables and conditional text settings. This lets you fully leverage the single-sourcing features of DITA, while continuing to deliver the high-quality PDFs that your customers expect. Additionally, the generated FM book file can be used as the basis for building various types of online Help through RoboHelp, WebWorks, or Flare (any tool that can import and process a FM book). In addition to automated publishing features, DITA-FMx also provides a number of authoring enhancements that makes it much more efficient to author DITA topics and maps in FrameMaker. Even if you're not using FrameMaker for authoring, you can still take advantage of its enhanced publishing features by using it as a publishing engine. You can also set up this process in an automated publishing pipeline using the FMx-Auto addon for DITA-FMx. Using FMx-Auto you can drive FrameMaker and DITA-FMx from a batch file or other command line scripting tools. This means that you should be able to easily call this process from your existing build process on a desktop system or from a CMS on your server. Don't lock yourself into a process that's more work and more expensive and produces lower quality results. Take advantage of your in-house expertise in FrameMaker template design rather than paying for development to outside contractors. Despite what "they" say, you can move to DITA without accepting a lower quality PDF output. Scott Prentice is the president of Leximation Inc., and has been in the technical publication field since 1991. His work focuses on custom online Help development, FrameMaker (plugin and structure application) development, as well as custom web application development. He is very involved with DITA and created the DITA-FMx plugin for FrameMaker.






---

Using Conditional Builds and Multiple TOCs in RoboHelp to Create Online Help, a Training Leader's Guide and a Training Participant's Manual

Beth Gerber, Lightext • Arcadia, CA

This project was designed for a start up, PennyMac Mortgage Company. Lightext developed the online help in RoboHelp when the company was less than a year old. The online help included all aspects of loan servicing and the end product was a large merged webhelp library. As management began to staff its call center and customer service divisions, there was an evident need for training. The company began to create training classes and develop their own material to support training. There were many challenges to this approach. The company had limited resources to develop training materials. The materials they did create were often in conflict with the online help. New employees utilized the training material instead of their online help when back at the workplace. There were no formal leader’s guides. Ongoing changes to procedures had to be updated in two sources: online help and training materials. Lightext recommended utilizing the content already developed in RoboHelp to create the online help and classroom training materials. Through the use of conditional builds and multiple TOCs we created three outputs: Online Help, Leader’s Guide and Participant’s Manual. The Participant’s Manual included exercises, quizzes, notes, graphics and other content specifically for use in the classroom. The Leader’s Guide mirrored the Participant’s Manual, but had leader’s notes, answers to quizzes, classroom set up guidelines and other important information. The Online Help contained an index and navigational features that would only be applicable online. All three outputs contained the same core content. As procedures are updated, all three outputs are updated simultaneously, thus reducing cost and duplication of material and effort. Trainees have confidence that the materials used in class reflect the same information as the online help used in the workplace. There is upfront planning and time involved with setting up the content. It's important to develop a simple style that will work well for all three outputs. It’s also necessary to work with the trainer to understand what’s required in the classroom. If the training objectives however are to teach essentially what your online help contains, this is an effective and cost saving solution. Beth Gerber is President of Lightext, a firm that specializes in quality consulting in the area of policy and procedure development, curriculum design and training delivery. Beth began her career as a Vice President for a nationwide bank and then took her expertise and built a company that models her commitment to high standards in the writing and training profession. The business recently expanded through the opening of the Lightext Training Center, certified by Adobe.






---

Using RoboSource Control and Perforce with a WebHelp System

Mark Whisler, Altera • San Jose, CA

Help for the Quartus II software, a leading electronic design automation package, is large, intricate, and evolving. Originally distributed as HTML Help files (.chm), the Help system has undergone transformation and migration because of changes to both the Quartus II software and the software used to create it. Altera Technical Communications converted from individual help authoring tools to RoboHelp in 2005. This presentation will be able to demonstrate: How to create and use a project database in RoboSource Control with SQL Server software The advantages of using Perforce for source control How RoboSource Control differs from Perforce The differences between project structure for HTML Help and WebHelp formats Various versions of the Quartus II Help System Mark will also be prepared to talk about numerous issues he has faced and resolved, including: Migration from version to version of the RoboHelp software and RoboSource Control Issues faced and resolved with RoboSource Control Changing to Perforce source control Command-line process for generating merged WebHelp Issues and improvements in the command-line processing system Archiving Resolving browser support issues Mark Whisler is a senior technical writer at Altera Corp., and has been their RoboHelp administrator since 2006. He has overseen migrations through four different versions of the RoboHelp HTML and managed the source control of project databases using both RoboSource Control and Perforce software for a team of up to a dozen writers. He also managed the project to convert the Help system from HTML Help format to WebHelp and oversees the daily Help system production process. Mark has performed nearly every task required to create, maintain, and distribute a large Help system.