2015 Technical Communication Summit Proceedings
Total Page:16
File Type:pdf, Size:1020Kb
Society for Technical Communication Summit Proceedings 21–24 June 2015 Columbus, Ohio #STC15 www.stc.org summit.stc.org1 Notice The papers published in these Proceedings were reproduced from originals furnished by the authors. The opinions expressed and integrity of the informa- tion are the responsibility of the authors and not the Society for Technical Communication (STC). STC grants permission to educators and academic libraries to distribute articles from these Proceedings for classroom purposes. There is no charge to these institutions provided they give credit to the author, the Proceedings, and STC. All others must request permission. All product and company names herein are the property of their respective owners. © 2015 Society for Technical Communication Contact Information Society for Technical Communication 9401 Lee Highway Suite 300 Fairfax, VA 22031 +1.703.522.4114 +1.703.522.2075 (fax) www.stc.org Colophon This publication was produced using Adobe InDesign CS6. The heading typefaces used are Helvetica, Helvetica Condensed, and Helvetica Ultra Condensed by Linotype and licensed through Adobe. The text is set in Georgia, which is licensed through Microsoft. This Proceedings publication was com- piled and designed by Michael Opsteegh. 2015 Technical Communication Summit Committee The Society for Technical Communication’s 62nd Annual Conference focuses on important trends in our profession. This publication contains papers submitted in support of the 2015 Summit conference sessions. This year’s conference is the result of the efforts of many individuals, including the Conference Manager, Program Advisory Committee, and staff of STC. Conference Chair Chris Hester Program Co-manager Karen Bachmann, Perficient Program Co-manager Pam Estes Brewer, Mercer University Track Managers Art, Design, and Visual Writing and Communication Communication Michelle Despres, CQG Adam Evans, kCura Tools and Technology/API Leadership and Management/ Documentation Consulting and Small Business Craig Baehr, Texas Tech University Management Jamie Gillenwater, Transcend Text, Training and Research LLC Adriane Hunt, CA Technologies Technical Communication Summit program, session, and conference information can be found on Lanyard at http://lanyrd.com/2015/stc15. Slides from the presentations can be found on Slideshare at http://www.slide- share.net/tag/stc15. 2015 STC Technical Communication Summit Proceedings i ii 2015 STC Technical Communication Summit Proceedings TABLE OF CONTENTS Art, Design, and Visual Communication BPMN Basics: What You Need to Know for Your Content Strategy 1 Jackie Damrau, Ph.D., Fellow Applying Users’ Mental Models to Information Design 11 David J. Dick, Fellow Tutorial Pacing 15 Viqui Dill Hypergraphics for Visual-First Help: SVG, CSS, JavaScript 19 David Gardiner Flipping Reports: Data for a Public Audience 27 Leah D. Hackleman-Good, Ph.D. Optimizing Sound for E-Learning 33 Robert Hershenow Using Scenarios to Help People Learn 37 Kim Lindsey Let’s Get Real: Creating Tangible Products 39 Marli Mesibov Stop Repeating Yourself! Use Video to Capture Knowledge 41 Matthew Pierce iii Delighting Mobile Customers with Content for Apps, Videos, and Social Media Campaigns 43 Marta Rauch, Associate Fellow, and Emily Hamer Leadership and Management Becoming a New Manager 51 Todd DeLuca Simple Scheduling 57 Mike Sawyer Copyright Licensing for Review and Reuse 61 Dylan Tuttle Tools and Technology Smoothing the Transition to DITA: Expert Partners Can Ease the Pain 67 Nicki L Davis, Ph.D., Associate Fellow Can Lightweight Markup Punch above its Weight? 71 Raymond Gillespie Git Started: Hands-On Git for Agile Writers 79 Sarah Kiniry Iterative Development Models and Process Improvement 85 Tina M. Kister, PMP EPUB: One Format for All Deliverables 93 Scott Prentice iv 2015 STC Technical Communication Summit Proceedings Training and Research Effects of Electronic Media on Technical/Scientific Communication: A Look at the BP/Horizon Deepwater Oil Rig Explosion 99 Carolyn Boiarsky, Ph.D., Associate Fellow Moving into Instructional Design 109 Stephen Van Esch Writing and Communication Developing and Delivering Sample Projects as User Assistance 113 Nicky Bleiel Clever Copy for Happy Users 115 Lauren T. G. Colton How to Make Sense of Any Mess 121 Abby Covert Performing a Global Audit 127 Leah Guren, Fellow A Cross-Discipline Approach to Content Strategy 131 Denise Kadilak Hardware Writing: You Can’t Always Touch It 135 Richard Lippincott, Associate Fellow What I Know Versus Reality 141 Cindy Pao, Associate Fellow 2015 STC Technical Communication Summit Proceedings v Don’t Just Shrink It; Rethink It! 143 Marta Rauch, Associate Fellow, and Jennifer Stout Getting Started in Policies and Procedures: Lessons Learned 149 Jamye Sagan Technology and Tools in Policies and Procedures 153 Louise Tincher API Documentation Survival Strategies: Building Your First Website for API Documentation 157 Mary Linderman and Andrei Essaoulov Consulting and Small Business Management Winning the Project with an Effective Proposal 165 Alisa Bonsignore Contract or Captive: Which Is Right for You? 167 Brenda Huettner, Fellow vi 2015 STC Technical Communication Summit Proceedings 2015 STC Technical Communication Summit Proceedings vii ART, DESIGN, AND VISUAL COMMUNICATION BPMN Basics: What You Need to Know for Your Content Strategy 1 Jackie Damrau, Ph.D., Fellow Applying Users’ Mental Models to Information Design 11 David J. Dick, Fellow Tutorial Pacing 15 Viqui Dill Hypergraphics for Visual-First Help: SVG, CSS, JavaScript 19 David Gardiner Flipping Reports: Data for a Public Audience 27 Leah D. Hackleman-Good, Ph.D. Optimizing Sound for E-Learning 33 Robert Hershenow Using Scenarios to Help People Learn 37 Kim Lindsey Let’s Get Real: Creating Tangible Products 39 Marli Mesibov Stop Repeating Yourself! Use Video to Capture Knowledge 41 Matthew Pierce Delighting Mobile Customers with Content for Apps, Videos, and Social Media Campaigns 43 Marta Rauch, Associate Fellow, and Emily Hamer 2015 STC Technical Communication Summit 21–24 June 2015 • Columbus, Ohio © 2015 Society for Technical Communication BPMN BASICS: WHAT YOU NEED TO KNOW FOR YOUR CONTENT STRATEGY Jackie Damrau, Ph.D., Fellow Business Process Management (BPM) and its Notation (BPMN) is an accepted practice for business analysts to model workflow concepts when writing business and technical requirements for developers to use in building applications. For content professionals, these same concepts can be useful in determining how to structure content, especially when encountering writer’s block. This session demonstrates how to model business pro- cesses using the BPMN 2.0 standard. Learning what a model, a process, and a process model are is critical to determining if a graphical model will represent your content bet- ter than traditional words. This is a brief introduction into the world of process mapping that is different than standard flowcharting. BPM Basics activity is performed or where or why it is performed. It barely touches on what the activity is or who per- usiness Process Management (BPM), according forms it. The “who performs it” part is dependent on Bto Search CIO (http://searchcio.techtarget.com), the model type you use. If you use a swimlane model, is a “systematic approach to making an organiza- then knowing the ‘who performs it” is required. tion’s workflow more effective, more efficient and Otherwise, you can use a freeflow model where the more capable of adapting to an ever-changing envi- “who performs it” is not identified. The activity flow ronment.” BPM encompasses using your technical is the most important part for assessing problem communication skills to describe information in spots in the process itself. understandable terms for an audience. The output of describing information can be in any form, like busi- When preparing for modeling, you can use process ness requirements or content strategy requirements. logic to help you elicit the right amount of informa- In those outputs, we place information into technical tion so that you can construct the process model and non-technical terms so that the respective audi- as well as using that same information to write ences understand the content being delivered. the business or technical requirements document that the developers and quality assurance teams A model is a graphical element (a visualization and use when building and testing applications. As you data entry device) that conveys meaning, specifically begin modeling, you need to know if the process you the logic of activity flow from process start to process are working on is a “current” (As-Is) or a “future” end. A process is a sequence of activities that maps (To-Be) process. Modeling an As-Is process is the possible paths (as much as possible, not all paths often easier than a To-Be; yet it is possible to elicit can or should be modeled) with all its successful enough information to build a To-Be process model. paths (“happy” path) or failures (“exception” path). Modeling the processes requires meeting directly Models help to reveal the order of activities, when with the subject matter experts (SMEs) who are the activities happen, and under what conditions the involved in the process (sometimes job shadowing activities occur. A model does not describe how an the actual performers of the process helps as well in identifying issues of which the SMEs may not be 1 Art, Design, and Visual Communication aware). During your SME meetings, you do not need rules in place to