Society for Technical Communication Summit Proceedings 21–24 June 2015 Columbus, Ohio
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.
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
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
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.
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
Flipping Reports: Data for a Public Audience 27 Leah D. Hackleman-Good, Ph.D.
iii Delighting Mobile Customers with Content for Apps, Videos, and Social Media Campaigns 43 Marta Rauch, Associate Fellow, and Emily Hamer
Smoothing the Transition to DITA: Expert Partners Can Ease the Pain 67 Nicki L Davis, Ph.D., Associate Fellow
Iterative Development Models and Process Improvement 85 Tina M. Kister, PMP
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
Clever Copy for Happy Users 115 Lauren T. G. Colton
Hardware Writing: You Can’t Always Touch It 135 Richard Lippincott, Associate Fellow
2015 STC Technical Communication Summit Proceedings v Don’t Just Shrink It; Rethink It! 143 Marta Rauch, Associate Fellow, and Jennifer Stout
Survival Strategies: Building Your First Website for API Documentation 157 Mary Linderman and Andrei Essaoulov
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
Flipping Reports: Data for a Public Audience 27 Leah D. Hackleman-Good, Ph.D.
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
aware). During your SME meetings, you do not need rules in place to prevent or guide the next to define every conceivable possibility. You should action state? cover the basic “happy” path and major exception paths that prevent business from occurring (As-Is These questions help you gather the information processes) or may prevent business from occurring needed for building the process model. As you (To-Be processes). build the model, additional questions may arise as you begin analyzing the process and laying out the During the process meetings with the SMEs, you model. Supplemental SME meetings are useful in might ask questions like: clarifying the process’s content as well as the accu- racy and completeness of the business or technical • How does the process actually start? What requirements. activity triggers it? Is there more than one possible way it can start? • What determines when the process is com- BPM Notation (BPMN) plete? Are there different end states (success versus failure)? The Object Management Group (OMG) governs the Business Process Modeling and Notation (BPMN) • How does the process go from Activity X to standard. The current standard, BPMN v2.0, has Activity Y? Does the person doing Activity Y been available since 3 January 2011. Visit http:// somehow know when to do it? www.omg.org/spec/BPMN/2.0/ to read the full 538- • How do you know when Activity X is done? page specification standard. Does Activity X always end in the same way? Are there any exceptions to how Activity X From the BPMN standard, OMG defines BPMN can end? Are there any specific business as a means of providing a “notation that is readily understandable by all business users, from the
Figure 1. BPMN 2.0 – Business Process Model and Notation (Source: http://bpmb.de/poster)
2 2015 STC Technical Communication Summit Proceedings BPMN Basics: What You Need to Know for Your Content Strategy
business analysts that create the initial drafts of the for you to gain the knowledge needed in modeling processes, to the technical developers responsible and understanding the field of business process for implementing the technology that will perform management. those processes, and finally, to the business people who will manage and monitor those processes. Thus, For some who have modeled in the past, the method BPMN creates a standardized bridge for the gap in which you model for a workflow engine system or between the business process design and process a Business Process Management Suite (BPMS) appli- implementation” (p. 31). This paper covers the mod- cation may be different. This paper does not specifi- eling notation with example models at a high-level. cally cover how to model for a system or application. However, feel free to contact me or do your own The BPMN objects can be overwhelming upon first research to discover the “correct” way of modeling if glance. However, not all objects are used in one pro- your process models will used by a workflow engine cess. Figure 1 shows a poster image of the available system or a BPMS application. BPMN objects. Now that you have briefly seen the BPMN objects, The BPM analyst should select the ones that are use- let’s take a look at the various process model types ful. In some cases, the company may select a subset that you can use in modeling your process content. of the BPMN objects and make that the corporate standard. In my last two companies, I recommended the use of a healthy subset of the BPMN objects Process Model Types (Figure 2). The types of process models that are available can Becoming familiar with the use of this notation isn’t vary depending on what you are trying to model. The as daunting as it looks. Several books and online ones listed here are just the few that I have exposure education courses or certifications are available
Figure 2. BPMN Objects for Process Modeling
2015 STC Technical Communication Summit Proceedings 3 Art, Design, and Visual Communication
to and frequently use. Each model type appears you have more than one Start or End object, you below with a small description of the flow itself. should label them accordingly so that anyone reading the process model can understand what the incoming and outgoing points are. Simple
A Simple process (Figure 3) has a Start and an End, Subprocesses (Simple—Expanded View) contains at least one User task (Receive Order), may have a Service task (Check Credit), and may have a A Subprocess (Simple – Expanded View) has the Subprocess task (Fulfill Order). A “Service Task” is same Simple process components, yet the “Fulfill one that the system performs with no human inter- Order” subprocess is now expanded within the same vention. A “Subprocess Task” is one that you do not process model (Figure 5). Note that the expanded want to show in this model; it can be contained on a Subprocess has its own Start and End notation and separate page or expanded later into the full model that the incoming connector stops at the beginning (see Figures 4 and 5). of the Subprocess object and the outgoing connector starts at the end of the Subprocess object.
Subprocesses (Separate Page) Exception Path (Simple) A Subprocess (Figure 4) has the same components as a Simple process, yet we introduce two new ele- An Exception Path (Figure 6) has the same Simple ments: a Decision Gateway (the diamond) that has a process components, yet it now includes two Yes/No path with two End path outcomes. Whenever Exception paths (“Credit OK?” and “In stock?”). In
Figure 3. Simple Process Model
Figure 4. Subprocess (Separate Page) Process Model
Figure 5. Subprocess (Simple – Expanded View) Process Model
Figure 6. Exception Path (Simple) Process Model
4 2015 STC Technical Communication Summit Proceedings BPMN Basics: What You Need to Know for Your Content Strategy
modeling this type of process, you should never as AND, OR, or XOR operators to split paths. A split have two Decision Gateways (diamonds) connected path can have more than one activity occurring at to each other. Each Decision should have an action the same time (parallel) or the one path completes (activity) that must occur before the next Decision before the next path starts (sequential). (This brings kicks off. back some algebra concepts that require thought.) Refer back to Figure 2 for the definitions to these operators. Whatever you do when modeling with Loopback these Decision Gateways, whatever object you use to split the path, you must use that same object to join A Loopback (Figure 7) starts to become a bit more the path. You cannot use an AND to split and an OR complex than the Simple process. Now, we are to join. beginning to show what happens when something doesn’t occur (“In stock?”) and the paths that must The bottom portion of the Decision Gateway in be taken to fulfill the request (“Offer Replacement Figure 8 shows two ways that the OMG standard Item” – “Accepted”) or cancel it (“Offer Replacement approves of splitting paths. The first two are my Item” – “Order failed”.) personal preference for easier readability. I’ve found that business and technical people get less confused that way. However, you must make your own deci- Decision Gateways (Parallel Split and Join) sion as to what you like best.
A Decision Gateway (Figure 8) begins the more complex modeling construct. You use objects known
Figure 7. Loopback Process Model
Figure 8. Decision Gateways (Parallel Split and Join) Process Model
2015 STC Technical Communication Summit Proceedings 5 Art, Design, and Visual Communication Swimlanes (Simple) Different Events, Activities, Data Elements, and Sequence Flows A Simple Swimlane (Figure 9) process is the same as the Simple process. The complete model is the pool The Different Events, Activities, Data Elements, and (Order Process) with the individual segments being Sequence Flows (Figure 11) process uses more of the lanes (Sales, Finance, Warehouse). The main dif- the BPMN objects from Figure 2 to show a complete ference here is that we are now putting the activities model with artifacts (“Order”, “Customer Account”) performed by a job role/department or a system into hanging off of their respective objects. Some process its own lane. This makes reading the process flow modelers need this additional detail when reviewing easier to understand and to see potential bottlenecks with the business to make sure that the information when looking at resource capacity. (Note: Never use is properly captured. actual names in your models. Always use a job role (Accountant) or department (Finance).) Reasons for Documenting BPM Processes
Swimlane Subprocess (Expanded) Documenting processes is important for a business to know where the work is being done, where the An Expanded Swimlane Subprocess (Figure 10) bottlenecks in that work are occurring, and what shows how you take the “Fulfill Order” subprocess actions need to be taken to resolve any potential and expand it within its specific lane. problems. Damelio cites seven reasons for mapping processes (pp. 32-33):
Figure 9. Swimlane (Simple) Process Model
6 2015 STC Technical Communication Summit Proceedings BPMN Basics: What You Need to Know for Your Content Strategy
• Help others “converge” upon the use of lan- • Improve communications and understanding guage and strengthen shared mental models within the workgroup. on how to think about what they do and how • Codify knowledge related to work. to improve upon that work. • Establish or make changes to the company’s • Level-set workgroup members on the context process architecture (workflow). of work they do (contributions to external customer value, part/whole workflow rela- • Follow an established framework depending tionships, and contribution or relationship to on the company’s industry (QMS, TQM, the company’s primary workflow). CMMI, Lean Six Sigma, Balanced Scorecard). • Make work architecture visible for sub- sequent action to improve upon the work, Software, Tools, and Repositories define or pilot alternatives, and assign ongo- ing workflow ownership. Every aspect of business today uses some form of modeling tools, internal/external storage reposito-
Figure 10. Swimlane (Expanded) Process Model
Figure 11. Different Events, Activities, Data Elements, and Sequence Flows Process Model
2015 STC Technical Communication Summit Proceedings 7 Art, Design, and Visual Communication ries, email/internal social media outlets, or websites/ artifacts that are relevant to the project, article sum- wikis to house all the information (knowledge). maries, new procedures, and team skills. The days of tribal knowledge walking out the door through attrition or reductions in force is lessening. These resources are great for working with infor- The items mentioned in this section are the ones mation, yet they still require workflow system that the author is most familiar with and have used. interaction. Workflow system interaction is proven Many other options are available depending upon to provide companies with agility through the use of your company’s needs. electronic systems to manage and monitor business processes. These electronic systems help in: Modeling Tools: For process modeling or concept map modeling, tools commonly used include simple • Defining and tracking workflow between ones like Microsoft Visio or Lucidchart (a cloud- individuals based option) to complex application suites like • Moving information in document form based ARIS Business Platform or Ultimus BPM Studio. upon defined processes
Storage Repositories: The common storage • Tracking the process of creating, reviewing, repositories we hear of or are using include and distributing documents for action SharePoint, Documentum, and TFS. Many compa- nies are moving away from SharePoint to TFS as they adopt the use of Agile in their requirements and Learning More About the development processes. Figure 12 shows a possible BPM Profession repository structure for consideration for your BPM projects. As you enter into the BPM world, you need to under- stand the field itself. Figure 13 gives a list of 14 things Email or Internal Social Media Outlets: that you need to feel comfortable in performing or Options available here include Yammer, Jive, have knowledge in when venturing into any project, Groupware especially a BPM project.
Websites/Wikis: Websites or wikis use internal software, like SharePoint or your favorite wiki software, for the sharing of insights and document
Figure 12. BPM Documentation Repository Example (Source: University of San Francisco)
8 2015 STC Technical Communication Summit Proceedings BPMN Basics: What You Need to Know for Your Content Strategy
Educationally, check out the following: • Widener University • Association for Information and Image Degrees Management (AIIM) Kelley School of Business • Object Management Group (OMG) • BS, Business with an Information & Process Management Major Professional associations to consider joining or at least checking on are: Widener University • Association of Business Process Management • MS, Business Process Innovation Professionals (ABPMP) Certifications • International Institute of Business Analysis (IIBA) • Boston University • BPM Institute.org • bpmessentials.com • University Alliance Conclusion • University of California – Irvine • University of Illinois – Springfield BPM is an exciting field for those who have a desire to analyze and improve business processes. This • University of North Carolina – Charlotte paper’s goal was to show you how to model workflow • University of San Francisco concepts using BPMN when writing business and technical requirements that developers use in build- • Villanova University ing applications and that quality assurance people
Figure 13. 14 Items You Should Know How To Do (Source: BPTrends)
2015 STC Technical Communication Summit Proceedings 9 Art, Design, and Visual Communication use in testing those applications. Content profession- als can use these same concepts in determining how to structure content, especially when encountering writer’s block.
“What is Business Process Management?” (http:// searchcio.techtarget.com/definition/ business-process-management) “Business Process Model and Notation (BPMN)” (http://www.omg.org/spec/BPMN/2.0/) BPMN 2.0 – Business Process Model and Notation Poster (http://bpmb.de/poster) Damelio, Robert. 2011. 2nd ed. New York, NY: Productivity Press. Basics of Process Mapping. Harmon, Paul. (2013, March 13). “What New Technology Should a Manager Use?” BPTrends Email Advisor (www.bptrends. com) University of San Francisco. 2013. Business Process Management Advanced Professional Certificate coursework and lectures.
Author Contact Information Dr. Jackie Damrau STC Fellow 5900 Baywater Drive, Apt. 501 Plano, TX 75093 +1.214.505.0100
Dr. Jackie Damrau is a Senior Business Systems Analyst with a leading commercial real estate com- pany with more than 25 years of technical commu- nication experience. She is a Fellow of the Society for Technical Communication (STC), member of the STC North Texas Lone Star chapter and the Instructional Design & Learning SIG, and the Book Review Editor for Technical Communication. Jackie enjoys reading classic literature, sociology, philoso- phy, and business process management. Find her on LinkedIn (http://www.linkedin.com/in/jackiedam- rau) or on Twitter (@damrauja).
10 2015 STC Technical Communication Summit Proceedings 2015 STC Technical Communication Summit 21–24 June 2015 • Columbus, Ohio © 2015 Society for Technical Communication
APPLYING USERS’ MENTAL MODELS TO INFORMATION DESIGN David J. Dick, Fellow
Cognitive psychology refers to the way we develop an understanding of how something works as a “mental model.” We develop mental models by observation and drawing conclusions about how something works. When products work the way we think they should work, we can successfully use them. When products do not work the way we think they should work, we get frustrated because we cannot successfully use them. So how can writers design information that addresses gaps between what the user knows about the product and what they need to learn about the product to understand how to use it successfully?
Designing With Users in Mind to that department (e.g., clothes, sporting goods, or household appliances). They compare prices of et us start with a high-level view of the concept similar products sold at other stores. They might ask Lof shopping in a store. I chose shopping because for advice or help from a sales clerk. Eventually, they it combines several processes and has evolved from buy something or leave the store with no purchases shopping in a store, to mail-order from a catalog, to (see Figure 1). Additionally, they might return an shopping online. When consumers shop in a store, item and ask for either a refund or an exchange. promotional items are placed at the entrance. If consumers know what they are looking for, they go When consumers shop online, they expect a com- parable experience as in a traditional store; if their online expectations are not met; they will probably become confused and frustrated. There might be minor differences in the process. For example, instead of speaking with a sales clerk, consumers will review customer comments. Instead of carrying the purchased item out of the store, consumers provide shipment information for a purchase. This difference will hopefully not cause confusion, especially if the consumers have ever shopped from a catalog. We cannot assume the consumer has shopped from a catalog, for simplicity sake—let us assume the con- sumer has shopped from a catalog.
The consumer applies the experience of shopping (Figure 1) to shopping online. Figure 2 shows what the consumer understands about the process of shopping online. Figure 1. User’s Mental Model of Shopping in a Store 11 Art, Design, and Visual Communication
functionality. This method helps you identify an overall structure for your information, as well as suggestions for explaining (and developing) navigation, menus, and possible taxonomies. • Mind Mapping. Mind mapping is a visual representation of the tasks and decisions users are taking to perform a task in order to identify possible gaps between the user’s mental model and the developer’s mental model. • Thinking Aloud. When users verbalize what they think, believe, and predict while they use the system, you can piece together Figure 2. User’s Mental Model of Shopping Online much of their mental model. To design user assistance for shopping online requires an understanding of the questions and concerns consumers have about the online shopping Methods to Help Users Develop process. Of course, it’s important to design the website to avoid a mismatch of the user’s mental Accurate Mental Models model about shopping online and how the website is actually designed. When users are struggling to understand the process of using a program, offer them different avenues to find the information they need. Manuals, online help, and instructional videos can appeal to people’s Why We Should Care About various learning styles; however, you need to offer Users’ Mental Models multiple methods in which users can build accurate mental models of the program. Mental models are a key concept in the develop- ment of instructions, tutorials, demos, and other • Marketing Brochures. A marketing bro- forms of user assistance. If we do not help users to chure answers questions about the product develop accurate mental models of how products in a logical sequence following the reader’s are designed, then we leave users on their own to train of thought. The best way to start is by develop their own mental models. If their mental analyzing what users want to know, and then models are not correct, users might have problems assess the order in which their questions will using the product, which makes for a frustrated user. flow. A good way to organize your points is to write down the questions you think a poten- tial reader might have and the answers your Practical Approaches to brochure might supply. Understanding User’s Mental Models • User Guides. For user guides to be useful, they need to need to be written for various There are several practical approaches to learning readers, ranging from those with little or about the user’s mental models. no experience with the product to those with significant experience with the product • Sketching. In the early stages of design, (or similar products). The ideal user guide invite users to explain their understanding of identifies the important high- and low-level every visual element of the product. If their processes that allow the reader to develop explanation does not match the design or the an accurate and useful understanding of the design does not match their understanding, product. then you have identified possible problems • Quick Reference Cards. Few people want that should be corrected in a redesign. to read a book cover-to-cover when they • Card Sorting. Card sorting is a reliable and only want to learn how to perform a few inexpensive method for finding patterns in key tasks. A quick reference card gives an how users would expect to find content or overview of the program and instructions on 12 2015 STC Technical Communication Summit Proceedings Applying Users’ Mental Models to Information Design
how to perform a few key tasks (e.g., create, Author Contact Information edit, delete). The user can always refer to the David J. Dick manual to learn more detailed information. Fairfax, Virginia Quick reference cards are an ideal takeaway [email protected] from any kind of training course. • Help. You are likely to find Help in most Author Biography programs and browser-based applications. For Help to be useful, it should allow users to David Dick is an STC Fellow, member of the search topics for individual tasks, as well as Washington, DC–Baltimore Chapter, and for patterns between common tasks. manager of the Usability and User Experience • Instructional Videos. If users do not like Special Interest Group. David is co-author of Web reading user guides, the next best thing is Services, Service-Oriented Architectures, and Cloud instructional videos, which help to reinforce Computing: The Savvy Manager’s Guide. You can concepts about how things work in a visual follow his musing about usability at http://note- and memorable way. Instructional videos book.stc.org/tag/david-dick/. are typically available from vendor sites and YouTube.
When you apply users’ mental models to information design, you help users develop accurate mental models. Moreover, you can raise awareness about product designs that do not match users’ mental models and suggest improvements.
Did you know that the proposition that people rely on mental models was first put forward by the Scottish psychologist Kenneth Craik in 1943. In his book The Nature of Exploration (Craik 1943), Craik wrote that the mind constructs “small-scale models” of reality that it uses to reason, to anticipate events and to underlie explanation. – Interaction Design Foundation
Norman, Don. 2013. The Design of Everyday Things: Revised and Expanded Edition. Basic Books. Nielsen, Jakob. October 2010. Mental Models. www. nngroup.com/articles/mental-models/. Davidson, Mary Jo, Laura Dove, and Julie Weltz. 15 November 1999. Mental Models and Usability. www.lauradove.info/reports/ mental%20models.htm
2015 STC Technical Communication Summit Proceedings 13 Art, Design, and Visual Communication
14 2015 STC Technical Communication Summit Proceedings 2015 STC Technical Communication Summit 21–24 June 2015 • Columbus, Ohio © 2015 Society for Technical Communication
Tutorials need to be paced carefully. Too fast and folks don’t learn. Too slow and they lose interest. This presentation discusses how to find a balance so that your tutorials are both engaging and effective, so that the pace is just right. Highlights include designing for the audience: creating engaged students by giving them what they need—to See/hear/touch, time to reflect, and to know what’s next; creating well-paced material that is “sticky”.
o you’re about to make a new tutorial for an no matter what the task is, they can do it if they just Saudience of folks who want to learn how to use a hang in with me and follow my instructions. brand new system. OK, so that’s who will do the learning and the watch- If you’re like me, you may never get to meet the ing and listening. Since these folks don’t work for my actual users. My company makes kitchen cabinets, company, I have no prayer of ever meeting them. which you can buy online. It’s really hard to buy a whole kitchen worth of cabinets and if you make Who will I be working with while I’m creating the a mistake, it’s usually a very costly and sometimes tutorial? Who will tell me what’s involved in each embarrassing mistake. My users are kitchen design- process? Who will give the final approval when I’m ers who take the home owner’s input and mea- done? I will be working with the MIS folks who have surements and turn the home owner’s dream into designed the system for the designers to use. These a design and a list of parts to order for the kitchen. guys and gals already know how to use the system. They will need to order everything from the cabinets They will already know how to do each task. They themselves on down to the decorative handles and will already know the answer to every question. They functional accessories like the wine rack and slide will be more concerned with accuracy and complete- out trash bin. ness of the content than with the effectiveness of the delivery. They will have very little patience for I always assume that any user who is desperate watching the tutorials teach them what they already enough to go to the online help is 3 things: know.
• New—they are new at the system and they So I have to be able to build a bridge from what the want reassurance that it will be worth their SMEs, Developers, and maybe even the Marketing time to use it. folks tell me to the actual needs of the actual users of • Alone—they are working alone at the the system. moment, otherwise they would have just asked a coworker the question. Too Fast or Too Slow • Bothered—they are either angry, or scared, or both. So let’s talk about pacing. Whatever I offer them in my tutorials and online help, I have to be complete and accurate. I have to gain the trust of my audience and reassure them that
New folks need o Read along • Time to see o Step by step • Time to read & hear o Pauses match video • Time to reflect • Time to interact § 0.5 seconds after caption
• To know what’s next § 1.0 second after screen change Well-paced material is “sticky” § 2.0 seconds for transition to next screen
Bored learners will o Explain concepts • Click off o Anticipate a question • Multitask o Overview or summarize • Not come back Pauses match content Well-paced material is engaging o § 0.5 seconds after a sentence
Visual Pacing and Audio Pacing § 1.0 second between ideas.
So let’s talk about two types of pacing, visual pacing § 3.0 seconds for reflection and audio pacing. Audio elements as objects
Visual tracking vs. visual focus
o Highlight box • Focus Figure 1. Audio sample o Highlight box or draw ovals Audio Energy o Show mouse click 0.5 seconds Too much vs. too little
Instruction vs. narration o Stimulating
o Contagious Interact • Skip intro option Putting It All Together • Clickable pacing
Combined pacing of audio and video: • Roll over text • Roll over graphics • Change slide • Review • Show what & where • Tell with voiceover What’s Next? Interactions • Focus visually • Show what & where Last slide offers choices • Review old tutorials • Move ahead to new tutorials • Email me • Online Help links • Links to external sites
Figure 2. Combined pacing of audio and video o See/hear/touch
Author Contact Information Viqui Dill Technical Communications Leader American Woodmark Corporation 131 Dawson Drive Winchester, VA 22602 +1.540.303.0323 Figure 3. Combined pacing of audio and video
2015 STC Technical Communication Summit Proceedings 17 Art, Design, and Visual Communication Author Biography
Viqui Dill is the STC Washington, DC - Metro Baltimore Chapter’s Social Media manager and uses various social media channels to spread good news about Technical Communications in our area. A technical writer for American Woodmark in Winchester, VA and an engineering graduate from Virginia Tech, Viqui is passionate about continued edu- cation and lifelong learning for those in our field.
Viqui describes herself as “Technical writer, wife and mom, bass player, worship leader. I’m happiest when folks sing along with me.” She would love to connect with you and invites you to email her at [email protected] or fol- low her on twitter @viqui_dill.
18 2015 STC Technical Communication Summit Proceedings 2015 STC Technical Communication Summit 21–24 June 2015 • Columbus, Ohio © 2015 Society for Technical Communication
Hypergraphics is an emerging area of visual communication that uses HTML5 technol- ogies. It allows technical communicators to sketch visual interfaces for mobile-first help, and shortcuts the process for translation/localization and online help documentation. Hyperlinked infographics, or interactive infographics, are a convergence of scalable vector graphics (SVG), cascading style sheets (CSS) and JavaScript – technologies for responsive web design. SVG is an enabling technology for interactive, visual-first, mobile- first documents. Applications include visual-first web app documents, multilingual graph- ics for translation/localization, and embedded video. Hypergraphics slot into existing workflows, and are compatible with help authoring tools for producing documentation as fragmented, stand-alone web topics.
Introduction SVG format—lines, shapes, text—can be hyperlinked. So anything you can draw, you can turn into a hyper- he increasing need to deliver online documen- link to navigate documentation. Ttation, the challenges in adapting content for mobile devices, and the demand for more interactive A number of trends in technical communication user experiences can be met with hypergraphics technologies and processes are seen as integrating (hyperlinked infographics). The HTML5 technology with and supporting SVG hypergraphics. HTML5 is of scalable vector graphics (SVG), together with now the web standard for presenting help content, CSS3 and JavaScript, can produce interactive and SVG is a new HTML element that is a vector illustrations as a visual alternative to text content. format for illustrations which can be displayed in SVG-based hypergraphics can be integrated into all major browsers. Cascading style sheets (CSS3), existing online documentation workflows, and web- and in particular media queries, work with SVG savvy technical communicators will adapt quickly to hypergraphics to change the display of graphics this XML format because of similar functionality to when adapting content for desktop and mobile HTML. Standard technical illustration and graphic devices. Some aspects of responsive web design can design software can output the graphics format for be applied to SVG interfaces, such as resizing graph- display in desktop and mobile browsers. Potential ics to fit browser width. Designing infographics and benefits for developing new visual interfaces visuals to support text-based procedures is becoming and reuse of graphics for translation make SVG more prominent in technical documentation, and hypergraphics a versatile enabling technology for interactive SVG infographics are used in other “visual-first” online help. There are instances where disciplines for representing statistical data. Video is authoring concept, task and reference topics might one such visual tool that is booming, and with some be better visualized as hypergraphics, so that users limitations, videos can be embedded in SVG illustra- would tap on a visualization of a product or service tions and played in browsers. Mobile-first produc- to find information. Individual parts of graphics in tion is emerging as content is increasingly presented online, and again SVG can be the basis for designing 19 Art, Design, and Visual Communication visual interfaces for devices. And SVG is amenable to of “background-color”, and “stroke” instead of “bor- incorporating design considerations of all these tools der-color”—which achieve similar visual styling for for delivering content, which ultimately enhances hypergraphics as standard CSS achieves for hyper- the user experience. text (Figure 1).
Responsive web design uses CSS3 media queries to HTML5 Standards modify web content for mobile devices (Perlin 2014). By specifying different browser widths using break- Scalable vector graphics is an XML-based format points, or changing the orientation of the device for displaying graphics in PDF and browsers. SVG (for example, tablets used in portrait or landscape is a text-based format much like HTML5 and shares format), graphics can show only the most relevant many similarities in markup, such as hyperlinking. information for smaller screens on mobile devices. The format is capable of enhancing vector graphics (e.g. illustrations) with interactivity, animation and Interactivity on mobile devices requires JavaScript filters (e.g. drop shadows and highlights). SVG has and jQuery to enable touch gestures such as pan in fact had a long history, having first become a W3C (swipe), zoom (pinch) and tap (touch). There are a recommendation in 1999. However, it has been number of JavaScript frameworks and libraries that a “sleeper” technology until 2011, with very little can be implemented with SVG to add an interactive development of potential applications. It’s taken experience that is expected when using mobile all this time for SVG to gain acceptance, mainly devices. Frameworks such as snap.svg, interact, because web browsers only gradually implemented Hammer.js and D3 offer various functionality for different functions of the SVG specification. At first, touch gestures. Technical communicators with a no browser could display SVG—it was for print docu- reasonable grasp of coding in general can implement ments only. Gradually, browser developers began to such open-source JavaScript frameworks with SVG support the format—Google Chrome, Firefox, Opera, and HTML5 with a minimal amount of JavaScript Safari and eventually Internet Explorer. Finally, with that needs to be hand-coded. the release of the Android 4.0 operating system for tablets in 2011, all desktop, mobile and smartphone browsers can display SVG. Building the Case for Hypergraphics
Cascading style sheets (CSS3), and particularly Opsteegh (2013:7), in the context of visualizing data, media queries, are compatible with SVG. This allows says that infographics can persuade the audience, user feedback for “mouse over” events to indicate and that readers tend to rely on information con- that a graphic element is hyperlinked. Either exter- veyed by infographics rather than any accompanying nal or internal style sheets can be added to an SVG text. So making the connections between these tech- file, class names added to each graphic in SVG, and nologies and user expectations leads to an inevitable class attributes specified so that a graphic changes need for hypergraphics that enable visual-first and color and line width increases when a user hovers mobile-first documents. the cursor over different parts of a graphic. For the most part, SVG uses the same CSS attributes as Technical communication practice is still wedded to HTML5. There are variations—such as “fill” instead the idea that infographics are static representations of concepts or processes that technical documenta- tion explains and summarizes—diagrams that are merely meant to be viewed to help a user understand complex systems. The best knowledge we have to portray visual information so far includes the con- cepts of “technical comics” and data visualization using infographics—which focuses almost exclusively on portraying statistical information such as for dashboard reports; such examples of infograph- ics have so far had little application in technical documentation. For the most part, graphics are still designed to be viewed and not to be interacted Figure 1. SVG markup showing similarities with HTML and with. But now we need to create content for mobile CSS elements. 20 2015 STC Technical Communication Summit Proceedings Hypergraphics for Visual-First Help: SVG, CSS, JavaScript
devices. There is now a timely convergence of needs. The idea of sketching documentation might web technologies, as well as demand for mobile also come more easily to new technical communi- documentation, that forces a rethink about how cators used to a world of visual information—the documents need to be presented to users who expect thought of learning how to write all documentation interactivity and highly visual interfaces. may seem archaic.
Replacing written concepts and tasks with hyper- linked infographics, or hypergraphics, has consid- Challenges in Mobile Documentation erable potential to improve the user experience because these act as shortcuts to understanding Cooper and Rockley (2014), in presenting trends in concepts, carrying out tasks, and finding reference mobile documentation, intimated that “We need an information quickly (Figure 2). Hypergraphics can alternative way to display tables on mobile devices.” potentially enable documentation—presently struc- Responsive data tables formatted with HTML tured as conventional, linear, book-like text—to be
elements have been proposed using CSS or fragmented into very small topics yet still accessible JavaScript solutions (Coyier 2012), where for exam- using graphics as the interface for finding informa- ple data is presented as a long and narrow table, or tion. It also opens up technical communication to by conditionally hiding less important columns. best practices in Web and mobile design, because succinct visuals linked to small topics convey more The issue of displaying tabular data for online help meaning and grab the attention of users who now became apparent to me in the early stages of writing expect an interactive experience akin to using web documentation for an ebook publishing prod- smartphones. uct. It was not until I conceptualized an interactive interface, and later tested the information design on Users expect fast learning and quick answers, so an Android tablet, that I realized SVG has the poten- presenting small and disparate web topics that are tial to solve the problem of formatting reference linked through visuals can begin to satisfy those tables, or rather their content, on mobile devices. Figure 2. User documentation interface showing components of a product and tasks as arrows between hypergraphics.
2015 STC Technical Communication Summit Proceedings 21 Art, Design, and Visual Communication
Conventionally, with paper manuals and PDF docu- up: the front cover, imprint page, table of contents, ments, reference information has been formatted as chapter title page, bibliography styles, and so on. tables. However, this way of showing information no Once I exported each graphic to SVG, I applied longer works well for mobile devices. styling to shapes (rectangles, arrows and lines) using a combination of SVG ‘filters’ (to add drop shadows) and CSS elements (to change the color of lines with Potential Applications “mouse over” events).
The challenges in adapting content for mobile Later I wrote DITA concept topics to design an devices—the barriers posed by text-intensive information structure for background concepts and book-like documentation that is difficult for users hypertext links to each hypergraphics page. Each to navigate, and presenting tabular data on small page of the resulting WebHelp documentation con- screens—can start to be overcome by reformatting tains concept information, and has an icon linking content using visual interfaces. Conceptualizing and to a hypergraphics page which contains infographics drawing hypergraphics is a cost in the time taken, so that link to reference information in standalone web there must be a benefit to make them a feasible part topics. So, rather than having reference topics for- of the document production workflow. Apart from matted as tables in the documentation (and accessed, creating a more engaging user experience that shows for example, by clicking on a link in the WebHelp only relevant task-based information, hypergraphics tripane’s table of contents), they are standalone web can fill gaps in delivering content on mobile and topics accessed by clicking on infographics that rep- desktop platforms.
Hypergraphic Web Topics
While developing WebHelp documentation for an ebook publishing product, I needed to present users with reference information about each style to set up, such as setting page margins, chapter title styles and options for paragraph line spacing. Before writing any concept topics, I started formatting the refer- ence data in conventional reference tables with DITA. I quickly realized it was overkill to first present users with lots of text in many tables that would then refer them to the style sheets, which again had lots of text users needed to scan through. Figure 3. Reference information in a hyperlinked web topic. The reference information had to have a visual inter- face, so that users could see in a browser the differ- resent the reference information (Figure 3). ent components of a book: the end product of using the style sheets. I also envisioned the end result of This information architecture is broadly consistent using the product—a book, and pages of a book—and with the concept of “Every Page is Page One” topics, had the idea of creating interactive graphics that which exist outside of a book-like structure, have no users could tap on to find reference information. The parent topic, and rely on linking to establish their intended audience was book editors and publishers, own context (Baker 2013:140). so I was already familiar with how those users would like to access reference information. To have doc- umentation that visually represents the end result Translation/localization of using the software would quickly orientate users with the features of the product and familiarize them SVG markup works with browser functionality in without too much reading. being able to display multilingual text in a browser. During document production, a translator can add I started drawing various pages of a book in Adobe translated text into an SVG file using a text editor, Illustrator to represent styles that users would set and special coding in the markup specifies the lan- guage of each piece of text. As the end result, when
22 2015 STC Technical Communication Summit Proceedings Hypergraphics for Visual-First Help: SVG, CSS, JavaScript
a user viewing the graphics sets their preferred lan- using a service. Or there could be an illustration guage in browser preferences, the browser interprets with a video embedded which engages users as an this coding and switches languages. e-learning tool.
In a way, this is “single-sourcing” graphics in that a The advantage of visual-first interfaces is that techni- technical communicator draws infographics once, cal communicators can sketch explanatory concepts and adds multilingual text to enable reuse of the and procedures designed for interactivity—anything visual content depending on how a user chooses to you can draw, you can hyperlink with SVG. Users view it (in this case, in the user’s native language). It see the product or service they are using to quickly means there is no need to create multiple images for become familiar with it, and get touch gestures that each language when producing graphics, because they would expect when using a mobile device. one graphic contains all translations and browser settings determine what language is displayed. A clear application of visual-first interfaces is for quick-start guides. For example, an online help document for a washing machine would contain Visual-first, Mobile-first Documents exhaustive details about safety information, various settings and procedures for different wash cycles, Graphics should be the first thing that a user inter- preparing clothes for washing, and specifications for acts with in documentation (such as a quick-start the machine. A new user simply wants to do their guide), such as an illustration of the product or first wash to get a feel for the product and not be service with links to concepts and procedures. In this overwhelmed by reading all the information, most of way, hypergraphics can restructure documentation which might be irrelevant for their needs. The first to have visual-first interfaces that quickly orientate page in online documentation could have interactive the user. A graphic could be a diagram of the product icons and diagrams of the washing machine with with interactive hotspots that link to web pages on hyperlinks to small parts of the document that have key features. Or it could be a process flowchart that key information to get started quickly. Numbered represents the steps a user needs to go through when steps take users through installing and setting up
Figure 4. Quick-start guide with interactive icons and videos to engage users with the product.
2015 STC Technical Communication Summit Proceedings 23 Art, Design, and Visual Communication
the machine for their first wash (Figure 4). This Adding hyperlinks to graphics can be done with approach means users don’t need to understand how WYSIWYG design tools such as CorelDRAW before to first navigate the document structure or be inun- exporting to SVG, although this can produce multi- dated with superfluous detail. ple xlink:href attributes for each graphical element that comprises an infographic, whereas ideally you only need one hyperlink for each infographic (com- Integrating Hypergraphics prising of multiple lines and shapes). Because SVG is text-based, then a text editor such as Notepad++ into Workflows or an XML editor can be used to add hyperlinks to infographics. Hypergraphics using SVG can be integrated into existing document production workflows that pro- For sophisticated applications such as multilingual duce online help. Wherever online documents are graphics as demonstrated in this paper, an XML produced using HTML, then SVG can similarly be editor or text editor is required to add valid SVG used for visual interfaces. markup. Also, JavaScript is essential to achieve more complex interactivity that uses browser functionality. Because there is no one graphics package that can Fortunately, only minor hand-coding is required handle all types of interactivity as demonstrated to implement JavaScript frameworks that support in this paper, a toolchain of software packages is touch gestures. required to: progress from initial design or sketch- ing; export SVG; clean up the coding; add hyperlink- ing to graphical elements; incorporate JavaScript functions and link to jQuery frameworks; and test Conclusion the output in browsers. A reasonable amount of hand-coding is required along the way, because Hypergraphics combines the principles of web producing or modifying hypergraphics cannot be design and information design. Extending the con- done entirely by WYSIWYG editors currently avail- cept to where the design process restructures written able. Some hand-coding is inevitable when inserting documentation into fragmented and modularized translated text for example. visual-first interfaces means also including aspects of infographic design applied to user assistance. Technical communicators can use standard illustra- tion software packages such as Adobe Illustrator or SVG represents a timely convergence of technolo- CorelDRAW to sketch graphics then export them as gies to help design visual document interfaces with SVG. These commercial tools produce “clean” SVG minimal outlay on production tools. A few technical markup with external or internal CSS styles. Other communicators are already using interactive SVG commercial graphic design tools claim that they are for applications such as aircraft parts catalogues and SVG editors, but one limitation is that when export- animating step-by-step procedures showing how ing SVG, “inline” CSS styles are generated for every to use products. By producing web documents, we graphic element—not only does this create problems already have many of the skills in markup languages when trying to change class styles using CSS (such to start creating hypergraphics. We can apply our as :hover color or line thickness) for a number of skills in designing documents for structure, hyper- graphical elements, but also there are redundant ele- linking and styling to improve the user experience, ments that must be deleted to allow for easier editing and start creating value-added documentation with of line and shape styles. While there are also spe- this highly accessible graphics format. cialized open-source SVG editors, such as Inkscape, these also suffer from extraneous markup such as namespace declarations and prefixes. The disadvan- Resources tage is that hypergraphics created and styled in one Cop-e-boox™ style sheets. http://sourceforge.net/ graphics tool might not be easily edited in another. projects/copebooxstylesheets/ For SVG that has inline CSS styles and redundant Gardiner, David. “Interactive Hypergraphics Design.” coding, it is recommended to clean the file using an Communicator (Winter 2014): 21-24. online tool SVGOptimiser. This removes namespace Gardiner, David. “Visualising Online Help Topics.” declarations and superfluous inline style attributes, Communicator (Spring 2015): 38-41. to produce a smaller file that is easier to edit later.
24 2015 STC Technical Communication Summit Proceedings Hypergraphics for Visual-First Help: SVG, CSS, JavaScript
Gardiner, David. Scalable Vector Graphics for Technical Communication. http://svgdocs.net
References
Baker, Mark. Every Page is Page One (Laguna Hills, CA: XML Press), 2013. Cooper, Charles, and Ann Rockley. The Future of Mobile Information—Examples and How We Get There (Proceedings, STC Summit Conference, 2014). Coyier, Chris (2012) “Responsive Data Table Roundup”. CSS Tricks (2012). http://css-tricks. com/responsive-data-table-roundup Opsteegh, Michael. “Planning and Creating Infographics.” Intercom (October 2013): 6–10. Perlin, Neil. (2014) “Responsive design.” Communicator (Summer 2014): 53.
Author Contact Information David Gardiner Xmplar 405 Burragorang Road Glenmore NSW 2570 +61.424003020
Author Biography
Dave Gardiner is a technical communicator currently working with an accounting software company. He has a decade of experience in technical and scientific document editing, redrawing illustrations, and ebook authoring. Dave has delivered industry workshops and conference presentations, and has published articles on XML document publishing technologies. He is qualified with the tekom first- level certificate in technical communication. Broad experience in graphic design for print and web includes digital mapping, preparing communications materials, website writing and design, and flowchart- ing with mind mapping software.
2015 STC Technical Communication Summit Proceedings 25 Art, Design, and Visual Communication
26 2015 STC Technical Communication Summit Proceedings 2015 STC Technical Communication Summit 21–24 June 2015 • Columbus, Ohio © 2015 Society for Technical Communication
FLIPPING REPORTS: DATA FOR A PUBLIC AUDIENCE Leah D. Hackleman-Good, Ph.D.
Reaching a public audience with report data or evaluation results? How can you grab its attention without dumbing down your story? Try a flipped report. Flipped reports turn the executive summary into a compelling visual document while leaving the granular data, nice-to-know information, and methods discussion to the appendix.
ometimes “technical” writing includes public doc- What to do? Suments that sit on the edge of advocacy: not quite academic reports, not quite marketing materials. The key is to go back to technical writing basics: analyze the purpose and the audience. Then figure out how visual displays will communicate to the audience and fulfill the purpose.
Figure 1. 2010 State of Poverty Report
27 Art, Design, and Visual Communication Case study
The Ohio Association of Community Action Agencies (OACAA) contracts with Community Research Partners (CRP) every other year to produce a State of Poverty report for Ohio. Typically these reports are 75–80 pages, about 25 of which are tables of all indi- cators for all 88 counties in the state. Past reports tended to resemble academic research papers (lots of gray text broken up by tables):
The audience includes the general public and the news media; it also includes state legislators who receive a copy of the report so they can find data on their counties and regions.
Opportunity Figure 2. Process The client did not want the report to look like a marketing brochure, but they were disheartened versus structure I proposed: that no one actually seemed to read the report. After 1. Opening letter the time and effort to research and write about the important poverty statistics in our state, it’s frus- 2. Seven important poverty subjects with trating that readers tended to use the report more graphics like they would use an online resource, looking for 3. Appendix with all data and notes the single piece of information they wanted and not attending to the rest. Challenges and tensions OACAA also realized that visual communications • Keeping the word count low work better with a public audience, but staff did not want too “slick” a presentation. Also, the report had • Keeping the images visually simple to be issued as a Word document so that partners • Integrating “stories” the client wanted within and other local Community Action organizations the new report could copy and paste the data.
What worked? Decisions and directions 1. Being involved immediately with the final The structure the report usually followed: client
1. Introduction 2. Providing research to back up the proposal
2. Defining poverty o Words versus images (and types of images) 3. Ohio poverty profile
4. Poverty and the recession o Cognitive load of most adult readers 5. Community Action and economic recovery 3. Visual simplicity based on structured writing 6. Final thoughts principles 7. Bibliography 4. Organizational simplicity for the audiences’ needs 8. Data appendix
28 2015 STC Technical Communication Summit Proceedings Flipping Reports: Data for a Public Audience
Figure 3. Results
Figure 4. News coverage of the reports
2015 STC Technical Communication Summit Proceedings 29 Art, Design, and Visual Communication
Results “Cmap Tools.” Florida Institute for Human & Machine Cognition. http://www.ihmc.us/ Notice by news outlets increased for the 2012 report cmaptools.php (that is, regarding the report as a whole rather than Evergreen, Stephanie. Presenting Data Effectively: simply using the report for numbers they need) com- Communicating Your Findings for Maximum pared to the prior year. Impact (Thousand Oaks, CA: Sage), 2013. Horn, Robert E. Participant’s Manual for Strategies for Developing High-Performance Other Applications Documentation (Waltham, MA: Information Mapping, Inc.), 1996. Sometimes a client will not accept a full-on visual display. But because they understand the impor- Ohio Association of Community Action Agencies. tance of visual communication in the era of online State of Poverty 2012 (Columbus, OH: access, we can encourage other clients to implement OACAA), 2012. http://www.oacaa.org/ flipping in another way. For example, in reports for wp-content/uploads/2013/01/State_of_ three different clients, I have developed a one-page Poverty_2012_Final.pdf “chapter opener” that draws attention to the most National Cancer Institute. Making Data Talk: A important (as determined by the client based on its Workbook (Washington, DC: National mission and the purpose of the report) data in that Institutes of Health, US Department of chapter. Health and Human Services), September 2011. Ware, Colin. Information Visualization: Perception References and Resources for Design (Amsterdam, Netherlands: Alley, Michael. The Craft of Scientific Presentations, Morgan 2nd ed. (New York, NY: Springer), 2013. Bateman, Scott, Regan L. Mandryk, Carl Acknowledgments Gutwin, Aaron Genest, David McDine, and Christopher Brooks. “Useful Junk? Thanks to Community Research Partners, especially The Effects of Visual Embellishment on Director of Research Yvonne Olivares, who was Comprehension and Memorability of Charts.” 100% in favor of fewer words and more impact and CHI 2010, April 10–15, 2010, Atlanta, who now owns Services for Data-Driven Solutions Georgia. (S4DDS.com) in Baltimore, Maryland.
Figure 5. Columbus Kids annual report (left); Clark County Status of Youth semi-annual report (center); 2014 Drug-Free Youth Survey, Franklin County (right)
30 2015 STC Technical Communication Summit Proceedings Flipping Reports: Data for a Public Audience Author Contact Information Leah D. Hackleman-Good Owner Editorial Partners LLC 3137 Meister Rd. SW Lancaster, OH 43130 +1.740.654.1260
Author Biography
I’ve been writing since age eight when I attended my first Young Authors’ conference in Ft. Wayne, Indiana, and as an adult I have worked as a technical writer, editor, and trainer. Since embracing my Mac 512Ke and HyperCard in 1987, I have loved using technology for written and visual communication, and for the past three years I have been designing and developing websites for small businesses and entrepreneurs using WordPress and Shopify.
Right now I’m most interested in using visual dis- plays to help present both data and concepts. I try to balance in the margin between marketing glitz and concrete data visualizations. Most of my clients are research, policy, and education organizations.
2015 STC Technical Communication Summit Proceedings 31 Art, Design, and Visual Communication
32 2015 STC Technical Communication Summit Proceedings 2015 STC Technical Communication Summit 21–24 June 2015 • Columbus, Ohio © 2015 Society for Technical Communication
OPTIMIZING SOUND FOR E-LEARNING Robert Hershenow
Quality sound is vitally important for electronic learning. It helps draw listeners in and makes narrative content more easily understood. A poor soundtrack can be annoying and hard to decipher, leading to audience disengagement and ineffective information transfer. This paper describes basic tools and methods needed to produce engaging audio that will help boost learning and enhance any presentation.
good soundtrack won’t save a bad presentation, How will you record? With a computer program? A but bad sound can quickly ruin a good one. And If so, a USB microphone (that plugs directly into a it doesn’t take much to make it “bad” – even slight computer and requires no additional parts) is most noise or distortion can distract and alienate an convenient. If you anticipate recording in the field, a online listener. The good news is that, with a bit of portable digital recorder is worth considering. knowledge and practice, it’s relatively easy to record and produce an effective soundtrack. See “Resources” for more information about select- ing and buying a microphone.
Microphones Software “How do I pick the best microphone?” Start with the five W’s (and an H): Many excellent recording and editing software programs are free, and many others offer free trials Who will use the microphone? If the answer is “just before you buy. Here are two excellent programs: one person,” then a headset might be perfect… but if several people will share it, a headset may not be so Audacity is a free, open-source recording and attractive. editing program that runs on multiple platforms. It’s basically quite simple but advanced features are What will you use the microphone for? Simply available as well, so – depending on which effects recording narration? Or will you also want to and add-ins you employ – you can work out your perform with it, or record guitar or environmental own level of complication. The program has an sounds? excellent online manual and a responsive user forum if you need help. Available from http://sourceforge. When and Where will you use it? As a fixed instal- net/projects/audacity/ lation on a desk at work? Or will you need to move it around? Perhaps you’ll want something pocket-sized Garageband is Apple’s recording/editing software for remote work? for the Mac and iOS, and as with most of Apple’s offerings it’s very easy to use. One popular feature is Why will you record? To produce Captivate a selection of presets for voice recording, to quickly soundtracks? CDs or DVDs? You’ll want a better and easily add ambience to your narrative tracks. microphone (or perhaps even a hired recording stu- Available from the App Store. dio) for a higher-fidelity release.
33 Art, Design, and Visual Communication Portable Recorders and try to finish, it will be very hard to make the second recording sound just like the first. Portable recorders from companies like TASCAM 5. Don’t touch the microphone! and Zoom offer convenience, ease of use, silent operation, and very good sound. Some models even feature Wi-Fi connectivity for remote control, Editing Tips wireless transfer and streaming. They can run on batteries, they record to microSD media, and fit in a 1. Save the original recording. Make a copy and pocket or bag. They are great solutions for recording edit that. interviews and capturing sound in the field, and their cost is comparable to that of a good microphone. 2. If you save incrementally, you won’t have to go back to the beginning if you need to Your phone or tablet can also be a high-quality rework a step. recording device, with the addition of a microphone 3. Process the entire recording (or big pieces or digital interface. Several companies offer micro- of it) before dividing it into smaller chunks. phones and interfaces designed for iOS, Android, Also, document your processes so you can and Mac/PC devices. duplicate them. 4. Go easy on the EQ. Cut rather than boost. If it sounds thin, try cutting the treble instead Technique of adding bass. 1. The qualities of the room in which you 5. Leave some room at the beginning and end record will affect the overall sound of the of each phrase for a more natural sound. recording. Experiment until you find a room 6. Use fade-ins and fade-outs for smooth tran- – or a corner of a room – that sounds good, sitions; don’t just chop. and record there. Be conscious of external noises that might contaminate the recording. Both room characteristics and external noise Resources can be lessened by placing the microphone closer to the source (i.e., your voice) and B&H Phot Video: Buying Guide – http://www. speaking louder, which will allow you to bhphotovideo.com/explora/audio/ decrease the record volume. buying-guides/voice-over-equipment 2. You can also shield yourself and the micro- Sweetwater Sound: Buying Guides – phone from noise and room characteristics Studio Mics http://www.sweetwater.com/insync/ by setting up a vocal booth, which can be as studio-microphone-buying-guide/ simple as a blanket draped over your head USB Mics http://www.sweetwater.com/insync/ and the microphone. Walk-in closets can usb-microphone-buying-guide-2/ make good vocal booths, as well. Headphones http://www.sweetwater.com/insync/ headphones-buying-guide/ Recording Tips Handhelds http://www.sweetwater.com/insync/ handheld-recorders-buying-guide/ 1. After you start the recorder, count to five before you start speaking. When finished IK Multimedia: Mobile Recording Accessories – speaking, count to five before you stop the http://www.ikmultimedia.com/products/ recorder. cat-view.php?C=mobile 2. Record ten seconds of your first take, then play it back to make sure everything is References working. Schroeder, Carla. The Book of Audacity. (San 3. Save the first take. It’s usually the best, even Francisco, CA: No Starch Press), 2011. if it doesn’t seem to be at the time. Rothermich, Edgar. Garageband 11: How it Works. 4. Do it all at once, if you can. Read your entire (Self-Published) http://dingdingmusic.com/ script. If you come back a day or two later DingDing/GB11.html
34 2015 STC Technical Communication Summit Proceedings Optimizing Sound for E-Learning
Blue Microphones. “Tips for Recording at Home.” Web. http://bluemic.com/blog/2013/10/15- tips-for-recording-at-home/.
Author Contact Information Robert Hershenow Principal RDH Communications 616 Colusa Ave Berkeley, CA 94707 +1.510.368.6355
Author Biography
Robert Hershenow has worked and played in audio for many years. He spent ten years in audio equip- ment manufacturing and has worked as a sound engineer, narrator, and musical performer. Robert is a senior member of the STC, Co-Manager of the IDL SIG, and is a technical communicator in Berkeley, California.
2015 STC Technical Communication Summit Proceedings 35 Art, Design, and Visual Communication
36 2015 STC Technical Communication Summit Proceedings 2015 STC Technical Communication Summit 21–24 June 2015 • Columbus, Ohio © 2015 Society for Technical Communication
USING SCENARIOS TO HELP PEOPLE LEARN Kim Lindsey
Scenario-based design is applicable across all instructional formats: e-learning, ILT, vILT, presentations, performance support materials, assessments, etc. This session defines what a scenario is, presents diverse examples of scenarios in training materials, and suggests appropriate scenario designs for a variety of purposes and audiences.
hought leaders in the training industry and Jimenez, Ray. Story-based eLearning Design Tmarketing gurus are aligning with current neu- Workshop. http://www.vignetteslearning. roscience research that describes how our brains com/vignettes/sbworkshop12.php. are “wired for story.” Learning retention increases significantly when information is presented in a narrative context. References Kapp, Karl M. “Abstract of Study Related In scenario-based instructional design, learners are to Storytelling.” Kapp Notes (23 placed into a story where the outcome - the conse- December 2014). http://karlkapp.com/ quences - are dependent on the choices they make. abstracts-of-study-related-to-storytelling/. The story may be long and involved or extremely short, but always enables people to learn from their Heath, Chip, and Dan Heath. Made to Stick: Why mistakes in a virtual, risk-free environment. Some Ideas Survive and Others Die (New York, NY: Random House), 2007. Scenario complexity is only one aspect of the variety made possible with this training format. Other Author Contact Information examples are: presence or absence of video or other media, style of graphics, branching vs. linear pathing, Kim, Lindsey and eLearning vs. instructor-led courses. While most eLearning & Instructional Design Manager scenarios have a main character of some kind, in Cinécraft Productions Inc. some cases the learner themself is the only character. 2515 Franklin Boulevard Cleveland OH 44113 The scenario format is thus adaptable to a broad +1.216.781.2300 range of learning and development needs and, since story-based information is maximally retained, Author Biography instructional designers and technical communicators should consider utilizing scenarios when designing Kim Lindsey is the eLearning & Instructional Design every type of deliverable. Manager at Cinécraft Productions Inc. in Cleveland Ohio. She is a Senior Member of STC and has held numerous offices in the Northeast Ohio STC chapter, Resources including President; she is currently the chapter’s Moore, Cathy. Scenario design: In-depth and Webmaster. Kim has completed several certificate hands-on. http://blog.cathy-moore.com/ courses on scenario-based design from industry scenario-design-online-course/. experts and enthusiastically shares how she has applied what she learned in real world projects.
37 Art, Design, and Visual Communication
38 2015 STC Technical Communication Summit Proceedings 2015 STC Technical Communication Summit 21–24 June 2015 • Columbus, Ohio © 2015 Society for Technical Communication
LET’S GET REAL: CREATING TANGIBLE PRODUCTS Marli Mesibov
Over the past four years, Lean UX has gained traction and earned a reputation for pro- ducing collaborative work, increased ideation, and ultimately better experiences—without deliverables. This paper outlines how to create sensible deliverables that can enhance the user experience, without falling into the pitfalls lean UX avoids.
hen I was twelve, it began to bother me that my UX designers – often considered “consultants” – this Wfriends were all immensely talented, creative, lack of deliverables can be met with a lack of respect. crafty, and artistic, and I was not. Many twelve-year- Worse still, no deliverables means that information olds suffer from insecurities of this sort. What makes gathered (via user research, discovery sessions, or my situation interesting is that I was an excellent collaborative workshops) lives within the minds athlete, and what upset me was seeing my friends of specific team members. Given that the average – mostly artists – creating beautiful, tangible, and American employee changes jobs roughly every four often useful things, while my talents seemed more years, we need a new plan – one that ensures teams ethereal, and therefore somehow less real. won’t lose content and context when members move on. Today, as a content strategist, I feel similarly drawn toward tangible deliverables: the things we leave behind with our clients. Sensible Deliverables
Just a year ago, Jeff Gothelf published a response When Does Lean Become to the many teams who have merely removed deliv- Deliverable-Free? erables from their process. “Lean UX is not Anti- deliverables,” he explained. “Reducing deliverables In 2011, Jeff Gothelf and Josh Seiden wrote a book, is only one relatively small benefit of shifting our entitled Lean UX. Published by O’Reilly Media, mindset away from traditional UX practices and the book served as both treatise and how-to, and thinking ‘lean.’” it successfully revolutionized how many teams approached user experience. Their goal was to focus The key is to create (a reduced number of) delivera- on experience rather than deliverables. The problem bles that enhance and guide the experience. Jeff and Jeff and Josh were solving for was a significant on: Josh identified that many UX designers struggle with the perception that they merely create “designs.” So “[UX designers are] measured and compensated for the first step to identifying a sensible, lean deliver- the depth and breadth of their deliverables instead able is to move away from the final product. of the quality and success of the experiences they design.” The second step is to ask: what would the client need, if I were to leave tomorrow? It sounds dramatic, but With this in mind, Lean UX became a proponent of ultimately, our goal for every project is to leave an no deliverables. However, for content strategists and intuitive, delightful, profitable experience without
39 Art, Design, and Visual Communication
the need for us to oversee it. With this in mind, a http://www.uxbooth.com/articles/ number of valuable deliverables come into play for research-right-audience/ visual designers, interaction designers, and content strategists alike, including: Author Contact Information • Style guide and brand guides Marli Mesibov • Interaction libraries Director of Content Strategy Mad*Pow • Conversational guidelines [email protected] • Governance workflows • Checklists and prioritization questionnaires Author Biography • Content audits Marli Mesibov is the Director of Content Strategy • User journeys at the design and UX agency Mad*Pow. Her work spans strategy and experiences across websites, web • User needs and business objectives applications, and mobile for enterprise companies • Analytics and measurement goals and startups. She is the managing editor at UX Booth, and a frequent conference speaker. Marli can also be found on Twitter, where she shares thoughts Think Forward on UX Design, content strategy, and Muppets. You can learn more about her and her work at http:// When Lean UX first came into being, deliverables marli.us were typically wireframes and mockups. Content strategists provided insight, user researchers provided data, but designers were the final (and only) creators. Today, that is no longer the case. Deliverables are the things we create internally to guide us on our journey. To provide a client with an experience, and not merely a design, we need to share our internal guides and teach them how to use our tools.
Additional Resources
Gothelf, Jeff. Seiden, Josh. Lean UX: Approaching Lean Principles to Improve User Experience. (O’Reilly) 2013. Gothelf, Jeff. Lean UX: Getting Out of the Deliverables Business. Smashing Magazine (March 7, 2011). http://www. smashingmagazine.com/2011/03/07/lean- ux-getting-out-of-the-deliverables-business/ Green, Eliza. 8 Tangible Deliverables of Content Strategy. Olive & Co (January 15, 2015). http://www.oliveandcompany.com/ blog/2015/01/20/8-tangible-deliverables-of- content-strategy Redish, Janice (Ginny). Letting Go of the Words: Writing Web Content that Works. (Redish & Associates) 2007. Wolfram-Hvass, Laurissa. Research for the Right Audience. UX Booth (August 12, 2014).
40 2015 STC Technical Communication Summit Proceedings 2015 STC Technical Communication Summit 21–24 June 2015 • Columbus, Ohio © 2015 Society for Technical Communication
STOP REPEATING YOURSELF! USE VIDEO TO CAPTURE KNOWLEDGE Matthew Pierce
Have you ever had someone decided to leave your organization only to realize that they were the sole keeper of a piece of knowledge? We’ve probably all seen it happen and felt the impact. Of course individuals are going to leave a company, but imagine if you could minimized that impact.
You’ve also probably had co-workers or customers ask you the same questions over and over. It’s not that this is a problem; it’s great to be knowledgeable and have our knowl- edge sought after, except when you have deadlines, or are in the middle of a project. Regardless of your role in an organization, but especially when working with technology, the opportunity to stop repeating the same answers and to capture knowledge before it’s gone is possible.
Virgin Media About using video Casson said, “What can be con- veyed in a three minute video is so much informa- irgin Media was faced with an interest challenge: tion that we can’t convey by writing it down. Video V150 employees were retiring and taking with allows us to capture and share tacit knowledge. The them critical knowledge. Given the timeline and knowledge that is in the head of a lot of our people opportunity, the team working to solve the problem who are very experienced at what they do.” couldn’t just rely on Subject Matter Experts (SMEs) to write down the knowledge. They wanted to pro- Especially in a company as large as Virgin Media, vide more context, more information, and make the Casson points out how tutorial videos of various tasks as easy as possible for the SMEs to capture the tasks and software can be reused across the com- knowledge. pany: “That one piece of content which was created to serve an individual’s need can actually serve hun- Casson McRae, a Learning Technology Designer at dreds or potentially thousands of people within an Virgin Media, took this challenge to heart. “A lot of organization very quickly and just by being created what we do in the learning technology team is to once by an expert user.” In light of the success with explore and try out new tools. By using these tools, their retiring workforce knowledge Virgin Media has [employees] are developing new behaviors that are rolled out the idea more broadly. They have scaled key for organizations in the 21st century.” Casson their program from the original 150 to approxi- and team knew that it would take a lot to get infor- mately 15,000 of their employees. mation out of employees’ heads and into a format that would capture needed details and be easy to digest. After looking at various solutions Virgin Media settled on using a tool to allow them to take screenshots and capture video.
41 Art, Design, and Visual Communication TechSmith (i.e., How do reset my password? How do I use the fax machine?) At TechSmith Corporation, using screenshots and • Capture information on how to use/run/ videos to communicate are a staple. One example is maintain a specialized piece of equipment how the Innovation Strategiest team returned from that other employees may not normally work customer visits with video field reports. Since not with. every employee has the opportunity to visit customer sites and hear the real challenges they are facing, • Provide high stake feedback, that needs to employees who go on visit are asked to report back include the tone of message to reduce confu- their experiences. These often would be shared in sion, and can be reviewed as needed by the the all-company meeting on Monday mornings or receiver. through email. Since not every employee can make • Create an on-demand presentation, that can the meeting, and many listeners won’t remember be seen anytime. the details of what was presented or read, Troy Stein, Senior Innovation Strategist, started to create field video reports. These quick two to three References minute reports were not polished or heavily edited but allowed him to share his experiences and find- Turner, Kelly “Virgin Media: Recording employee ings while they were still fresh in his mind, often knowledge” TechSmith Blog (7.10.2014). just minutes after completing a visit. Because the http://blogs.techsmith.com/customer- thoughts were recorded, anyone who wanted the stories/virgin-media-recording-employee- information could access it as needed it, and have knowledge/. the benefit of clarity of listening to Troy convey “Empowering Colleagues to Share Knowledge cleary tone. Companywide” TechSmith.com. https:// www.techsmith.com/customer-stories- TechSmith technical support also uses video fre- virgin-media.html. quently as they try to help customers solve technical issues. Once the team has identified an issue that is beginning to develop a recurring frequency in Author Contact Information written and phone cases a member of the team will Matthew Pierce develop support materials. Nick Herber, Technical Integrated Marketing Manager Support Manager, says, “Especially when complexity TechSmith is high, we turn to videos to ensure that the customer 2405 Woodlake Dr is able to follow the steps precisely as we present Okemos, MI 48864 them. We started using a short video or screenshot +1.517.381.2300 to accompany our directions because we had a lot of overly detailed steps and long menu items, as well as item menus with name similarity.” Author Biography
Matt Pierce works for TechSmith Corp., a software Potential Opportunities company that provides practical business and academic solutions that change how people commu- nicate and collaborate across devices. Matt currently Both Virgin Media and TechSmith showcase a few leads the Social Media, PR, and Customer Stories examples of how video and images can help you team. Prior to working in marketing, Matt managed from having to repeat yourself. Below are a few other training, technical support, and has been an instruc- ideas that organizations might want to employ to tional designer. He is a regular contributed to several help save time and effort in their communications: online publications in the U.S. and UK. • Record personalized demos of material for customers or stake holders. • Record the proceedings of critical meetings for anyone who is unable to attend. • Answer questions that occur at a regular fre- quency or for items that are easily forgotten 42 2015 STC Technical Communication Summit Proceedings 2015 STC Technical Communication Summit 21–24 June 2015 • Columbus, Ohio © 2015 Society for Technical Communication
DELIGHTING MOBILE CUSTOMERS WITH CONTENT FOR APPS, VIDEOS, AND SOCIAL MEDIA CAMPAIGNS Marta Rauch, Associate Fellow, and Emily Hamer
For mobile projects, you can increase customer satisfaction by developing content for mobile apps, videos, and social media campaigns.
o delight mobile customers, provide useful We share these best practices for adding value and Tcontent for mobile apps, develop mobile videos, enhancing customer experience on your mobile and roll out social media campaigns. Here are tips products: and strategies for leveraging your content across multiple channels, measuring the benefits, and com- • Provide adaptive content municating the results. • Create a mobile friendly library • Develop a mobile video • Run a social media campaign
Figure 1. Example of mobile content
43 Art, Design, and Visual Communication • Get feedback Create a Mobile-Friendly Library • Communicate wins Many mobile apps link to a library of content, FAQs, and other resources. Ensure that your library and its Provide Mobile-friendly, contents are mobile-friendly. As you develop content, check the library and your content on the devices Adaptive Content that your target customers use. Install the app on a mobile device, and then test the link to the library Ensure that your content is mobile friendly. As you from the mobile app. see here, mobile app content includes: Design the library and its contents with mobile in • All text on mobile screens mind. Content should look great on desktops, lap- • Hints and tips on screens and in fields tops, and mobile devices. For a quick test in a desktop • Messages browser, resize the browser page to the size of the Many apps include a mobile in-product tour. These mobile device. tours help users: Content should respond to: • Learn key tasks while without leaving the app • Computer or mobile device • Quickly get up to speed on mobile features • Screen size • Finish the tour when they want, and come • Operating system back to review content anytime • Portrait and landscape mode • Save time and money by leveraging your Mobile library best practices: mobile content across multiple channels: • App store descriptions • Responsive design, for example, through HTML5 and CSS3 • Content embedded in the app • Easy to read on desktop, laptop, and mobile • Video scripts and captions devices • YouTube video, channel descriptions • Tested on mobile devices • Social media campaigns and posts • Links to mobile videos • Blogs and marketing communications Encourage user engagement with your library con- • Mobile-friendly library tent. Enable users to:
Strategic considerations when developing content: • Add comments • For app store descriptions, plan for app store • Provide ratings updates. App store content must be updated • Recommend content whenever your company updates the app with features or fixes. • Create collections • Your mobile app’s End User License • Use enhanced search Agreement (EULA) links to an End User • Post to their social networks License Agreement. EULA text originates from the legal department, but some compa- nies require that technical communicators Edit, Edit, Edit host the EULA on the web. If this is the case, plan where to post the EULA, when to For mobile content on small screens, you must edit provide the link to developers for the apps ruthlessly. While writing or editing, ask yourself: and app stores, and when to test the links on mobile devices. • What is the primary purpose of this screen?
44 2015 STC Technical Communication Summit Proceedings Delighting Mobile Customers with Content for Apps, Videos, and Social Media Campaigns
• Will users know what to do within three Announce videos to your company as they are being seconds? produced. You can also spread the word by providing the video URL and description to sales and market- • Is the information too dense? What can you ing teams. As teams promote it on their channels, remove? (Rachel Hinman, http://rachelhin- your video will be highlighted in blogs and social man.com/) networks, and it may be shown at conferences and • Develop mobile style guidelines and adhere demos. to them. Periodically, search on the web for your video and product to find third-party posts. Our video was Create Mobile Videos featured as a “Top Pick” on a mobile video app. This honor increased the number of views and provided Videos are a helpful way to engage users in mobile publicity for the product. apps. A best practice is to post a video with a mobile screencast showing key tasks. Run a Social Network Campaign Reflector is a useful tool for capturing mobile screen- casts, and it now supports Android and iOS devices. Social network posts bring attention to the mobile With Reflector, you can display a mobile screencast app and encourage users to download it from the on a laptop or desktop computer, where you can app store. Technical communicators can contribute easily edit it. Use Reflector to get the screencast from by posting to the department’s social networks. the mobile device to a laptop. Then use Camtasia or Before you start your campaign, understand your another editing tool to produce the video. company’s social network guidelines and policies, and get permission for your campaign. An effective mobile video production process for an iPad video edited on a PC: Next, understand your audience and develop your strategy. Create a timeline, decide on the networks, 1. Start Reflector on the PC. and create a schedule. Additional strategies for 2. Connect the PC and iPad to the same wire- social media campaigns are detailed in Marta less network. Rauch’s presentation on Innovations in User 3. Connect the iPad with Mirroring to the PC. Assistance, http://www.slideshare.net/MartaRauch/ rauch-innovations-inuserassistancewritersua2012. 4. Record the screencast on the PC with Camtasia. Next, plan your posts. To save time and ensure con- 5. Edit and publish the video to YouTube. sistency, leverage content you have already devel- oped for the product. For example, you can reuse the In the video’s call to action, include links to mobile new feature points that you developed for the app app stores. You can also include the links in the vid- store as Twitter posts. Before posting, hold a review eo’s description on the YouTube page. If you include of your posts and get signoff from stakeholders. shortened links using Bit.ly, you can track the traffic driven to the app store from your video. In each of your posts, include links to additional information. Links can point users to download the app from the app stores, view blogs, or watch videos. Maximize Video Views Before your campaign, use Bit.ly to shorten links to the app store pages, library, and videos. Later, you A video is effective only if it is seen by the target can use Bit.ly analytics to track the effectiveness of users. To increase the number of views, collaborate your posts. with administrators of your company’s YouTube Post on your department’s social networks, and channels to create mobile playlists that point to your coordinate with other social network administrators video. On a recent video, the author created playlists at your company to share information. Depending on several corporate YouTube channels, including on your company’s policy and your target users, you curriculum development, pushing the video to more may post on Twitter, Facebook, Google+, Pinterest, than 4,482 views worldwide. Instagram, and YouTube.
2015 STC Technical Communication Summit Proceedings 45 Art, Design, and Visual Communication Tips for selected social networks: Communicate Wins
• Twitter: Use shortened links and include It is important to communicate your team’s success relevant hashtags. to internal stakeholders. This helps demonstrate the • Facebook: Post on your department or effectiveness of your content and team. It shows how company’s page. Include pictures to invite you contributed to customer satisfaction by increas- engagement. ing engagement with the product. To communicate wins, gather metrics and share key highlights. • LinkedIn: If your product’s target users are members of groups on LinkedIn, find out which groups they are in, and post there. Gather Metrics • Google+: Include Google+. It is helpful for SEO (search engine optimization) and is Examples of metrics you can gather and integrated with YouTube. Pictures and vid- communicate: eos increase interaction. • Engagement • YouTube: Your Google+ posts are displayed on YouTube and invite engagement directly • Follower growth on your video’s YouTube page. • Page views • Time on page Get Feedback from Customers • Actions • Downloads Get customer feedback to validate your content. An especially beneficial way to get feedback is through a • Interview feedback customer partner program. For detailed information on customer partnering and other ways to get cus- These social networks have built-in effective analyt- tomer feedback, see Marta Rauch’s article for CIDM ics tools: Best Practices: http://www.infomanagementcenter. • Facebook: View Facebook page insights for com/members/pdfs/reprints/BP09-12MRauch.pdf your page Key points for customer partnering: • YouTube: Check analytics for your video to learn which mobile devices viewers are using • To find customers, get leads from your com- to watch pany’s marketing, sales, product marketing, and user experience teams. • Twitter: Go to https://analytics.twitter. com/user/TwitterID/tweets • Select representative customers who have a mix of products and releases. • Hold quarterly webcasts. • Use questionnaires, mind maps, and other methods to gather feedback.
During a recent customer partner meeting, the authors gave a demo of mobile content and requested feedback. In return, we got helpful sugges- tions and positive feedback on our mobile content. We then shared a sample of this feedback with stake- holders to validate our contributions to customer satisfaction. Figure 2. Twitter Analytics
For Google+, CircleCount provides detailed metrics on your posts. An effective tool for web analytics is Adobe Site Catalyst. Bit.ly provides metrics on your
46 2015 STC Technical Communication Summit Proceedings Delighting Mobile Customers with Content for Apps, Videos, and Social Media Campaigns
shortened links. For web analytics, an effective tool social networks. The posts give me informa- is Adobe Site Catalyst. tion in real time to help customers upgrade.” • Mobile video: “I like seeing the product in use with a live Share Key Highlights demo in the video.” “Your YouTube channel is my go-to location Share highlights of analytics and customer feedback for finding your videos.” to communicate results to executives and stakehold- “I subscribe to your video channel and get ers at your company. notifications when new videos come out.” When executives demo your product, watch the ses- sion and post updates on social media with a link to the product. For example, when an executive spoke Conclusion about the author’s product at the company’s yearly This article describes several effective strategies for customer conference, the author posted about the delighting mobile customers. Use these best prac- session on social networks with a shortened link to tices to contribute to the success of your own mobile the Apple and Google Play app stores. products by creating helpful content for mobile apps, A few hours later, Bit.ly metrics showed that the developing videos, and running social media cam- posts drove 443 visits to the mobile apps on both paigns. Leverage content across multiple channels, app stores. Executives, of course, were pleased about measure benefits, and communicate results to add the metrics. value and delight your mobile customers. For details on this presentation, see Marta Rauch’s slides on SlideShare: http://www.slideshare.net/ MartaRauch/presentations
Note: The views in this article are the authors’ own and do not necessarily represent those of Oracle.
Safe Harbor Statement
Figure 3. Sharing key highlights of a social media The preceding is intended to outline our general campaign product direction. It is intended for information purposes only, and may not be incorporated into any contract. It is not a commitment to deliver any For example, after a customer partnering demo of material, code, or functionality, and should not be mobile content, the author shared these quotes from relied upon in making purchasing decisions. The key customers: development, release, and timing of any features • Mobile content: or functionality described for Oracle’s products “The mobile tour is great. It helps you get remains at the sole discretion of Oracle. started, and has just the right amount of information.” “The mobile content and library are useful.” Resources “I like being able to give feedback and add Marta Rauch SlideShare, http://www.slideshare.net/ comments and reviews.” MartaRauch/presentations • Social networks: Marta Rauch Pinterest boards: http://www.pinterest. “I follow you on all of your social networks. I com/martarauch/ stay up to the minute and get your RSS feed in my inbox.” Developing User Assistance for Mobile Apps, by Joe “I follow you on LinkedIn and Google+. Welinske LinkedIn is my favorite network, and I check The Language of Content Strategy (includes Marta’s it daily.” topic), by Scott Abel and Rahel Bailie “I appreciate the great work you’re doing with 2015 STC Technical Communication Summit Proceedings 47 Art, Design, and Visual Communication
Managing Enterprise Content: A Unified Content personal networks, she has over 165,000 connec- Strategy, by Ann Rockley tions and a Klout score of 77. She is in the top 160 Content Strategy for Mobile, by Karen McGrane U.S. women on Google+. Responsive Web Design, Ethan Marcotte An STC Associate Fellow, Marta has received 15 STC Oracle Application Express awards for individual and team projects at Twitter Analytics: https://analytics.twitter.com/ the regional and international level. She is VP of STC Silicon Valley and a member of the STC Facebook Insights: https://www.facebook.com/ Nominating Committee. Marta graduated from business/news/pageinsights Stanford University and earned certification in CircleCount Google+ analytics: http://www. technical communication from the University of circlecount.com/ California Extension. Guy Kawasaki, What the Plus Google+ guide, http:// www.guykawasaki.com/what-the-plus/ Emily Hamer is a principal information developer at Oracle, where she works with different teams to Guy Kawasaki, Enchantment, http://www. develop content and video-based user assistance guykawasaki.com/enchantment/ for Public Sector Planning and Budgeting and mobile and cloud products. Emily enjoys launching Author Information social media campaigns to introduce new products, showcase functional enhancements, and engage Marta Rauch customers. Senior Principal Information Developer Oracle @martarauch LinkedIn
Emily Hamer Principal Information Developer Oracle @ETSHamer LinkedIn
Author Biography
Marta Rauch is a senior principal information developer at Oracle, where she leads mobile, cloud, and REST API projects. She develops content strategy and content for iOS and Android apps on Google Play and the Apple app store. Marta enjoys participating in design jams and developer chal- lenges for mobile apps, gamification, beacons, aug- mented reality, and the next generation of mobile, wearable technology.
A frequent presenter for conferences and webinars, Marta has published articles for IEEE, HCII, STC Intercom, and CIDM Best Practices. She contrib- uted information to Developing User Assistance for Mobile Apps, by Joe Welinske, and her augmented reality topic appears in The Language of Content Strategy by Rahel Bailie and Scott Abel.
Marta enjoys creating mobile videos and running social media campaigns to engage customers. On her
48 2015 STC Technical Communication Summit Proceedings Delighting Mobile Customers with Content for Apps, Videos, and Social Media Campaigns
2015 STC Technical Communication Summit Proceedings 49 LEADERSHIP AND MANAGEMENT
Becoming a New Manager 51 Todd DeLuca
Simple Scheduling 57 Mike Sawyer
Copyright Licensing for Review and Reuse 61 Dylan Tuttle 2015 STC Technical Communication Summit 21–24 June 2015 • Columbus, Ohio © 2015 Society for Technical Communication
BECOMING A NEW MANAGER Todd DeLuca
How do you go from being a member of a team to leading it? It takes dedication, commit- ment, and hard work—but is that enough? Are you sure that you want to be a manager and are prepared for the job? This proceedings paper provides some answers to those questions and outlines the ‘Becoming a New Manager’ presentation being given at the 2015 STC Summit in Columbus, Ohio.
verybody’s path to becoming a leader is unique. ager position to lead it—it had just been proposed ESome paths are straightforward and relatively and created, based on the foundation and trust that predictable while others follow a very haphazard and I didn’t realize I’d been building within the organiza- unexpected route (like mine). However, regardless tion. An unusual but true story. of the position title (manager, supervisor, team lead, or something else) and the circumstances on So how is it that I was able to get a manager position how it is achieved, there are certain qualities and if I didn’t work as part of a technical communication characteristics that make potential candidates shine team and wasn’t able to demonstrate any direct ‘on enough for others to take the chance on giving them the job’ supervisory experience? Well, I can’t say for the extra responsibility that comes with leading sure (you’d have to ask my former manager), but I others. In this paper, I will discuss some of those key strongly suspect that there were various experiences characteristics, describe things that I did to prepare and other things I was doing to stand out from for management, and list activities that you should others (in a good way) that were key in getting the consider as you prepare for the next potential stop in new job. Plus I was documenting and sharing those your career. I will also outline new manager respons- experiences, making it clear that I was looking for an bilities and offer some advice on deciding if being a opportunity to advance. I’ll talk about these activities manager is the right fit (it’s not for everyone). Just in more detail and provide some examples later in ahead—Management, YOU. this essay.
One Person’s Trip Leadership Is a Journey
I’ve mentioned that everyone has a different path to I believe that leadership is a journey, not a desti- leadership. Basically, it’s very difficult to say what nation. Regardless of the actual position or title a ‘normal’ scenario is for somebody who becomes a (manager, supervisor, team lead, whatever)—it’s just new manager (there’s no recipe). Perhaps you work a stop along a greater career path. It’s a road trip! on a team and as a senior member end up replacing an existing manager who resigns or retires. Maybe Of course some trips and the paths and routes you work in a growing company and as the most taken to advance in a career are bumpier and take ‘seasoned’ person end up leading an expanding team longer than others, which is just one part of what of less experienced people. Neither of those sce- make everyone’s journey unique. Many factors can narios applied to my situation. In fact, when I was also influence your trip—weather, road conditions, promoted there was no Technical Communications climate, terrain, and so on. I use this analogy to team (it was a brand new department) and no man- help paint a picture and demonstrate that the step
51 Leadership and Management
from individual contributor to leader is rarely as Here are some sample questions: straightforward and predictable as we think it might (or should) be. • What kind of leader are you? Hands off or hands on? • Would you rather supervise or be a direct Preparing for the Trip manager? What level of responsibility are you comfortable with? There are three general things you should do before • Do you want to continue doing your current you decide whether or not you’re ready or want to job? Do you like producing content and grab the wheel and get off on the management exit. doing things for yourself? 1. Take an Inventory Ask key questions so that you understand What’s Your Motivation? why you want to advance and to determine how ready you are to start the journey. Do It’s important to think about what is driving your you know where you want to go or just that desire to advance. It’s not always what you expect you want to get moving? when you take the time to think a little deeper. 2. Set Your Course Before you hit the road, take stock of your • Are you looking for more responsibility? situation and analyze your surroundings to • Do you want to earn more money? better know your chances of getting the next position and where you’re most likely to find • Do you desire more respect or authority to the opportunity. Also look for others who can make changes? assist or support you during the trip. • Are you looking for a change of scenery?
3. Hit the Road I can tell you that if you answer ‘Yes’ to any or all of Chart your course and start to perform con- those questions, then you don’t necessarily need to crete actions and activities so you’re ready to be a manager to get those things (and might consider pull off when the opportunity comes up. Pack alternate ways to achieve your goal). the car and start driving!
Taking an Inventory What are Your Expectations?
Before you start traveling, it’s important to get a Each leader or manager position in an organization better understanding of the motivations and reasons has different job responsibilities, so you should why you think you want to be a manager (or should consider what’s required before you decide to jump be promoted to one). I suggest breaking this analysis in and go for it. For example, you may find that the into two sets of questions, similar to how you would next-level supervisory role just adds some extra prepare for an interview. reporting and human resources duties and doesn’t pay much more for the extra work. The first set of questions are things you should ask yourself. They are intended to help clarify your expectations and rationale for advancement—to help Packing Your Bag make sure that being a manager is what you really want to do. After you’ve done some self-analysis, it’s time to put yourself in the shoes of the people who might hire or recommend you for advancement. Coming from this Why Do You Want to be a Manager? angle will help you gauge how prepared you really are to take the next step. You need to be able to explain and understand your thinking to this basic question if you want to prepare The second set of questions can help you explain to and be successful. others why promoting you is an obvious choice (and also help prepare you improve your odds of getting a more advanced position).
52 2015 STC Technical Communication Summit Proceedings Becoming a New Manager
What are Your Strengths? • Are you close to getting or qualifying for a supervisory or team lead position? You need to be prepared to give solid reasons and • Are there any current or expected openings? examples of skills that make you stand out from a potential pool of other candidates. Look Out For Other Drivers
• How do these skills translate to being a • What sort of competition is out there? Is it leader? the current position holder or others in your group a potential candidate for the job you’re interested in? What Experience Do You Have as a Leader? • Who are the most qualified or experienced Write down examples of experiences that demon- people who could get the job? Hopefully it’s strate how you have led others in the past (with you. work or other situations, such as volunteering or in a professional organization - like STC). Identify Potential Tripmates • Are there others who might support you or act as a reference? What People Skills Do You Have? • Is there an insider who can give you solid • How well do you get along with others, both information or advice on the position? in your group and with other teams? • Do you know someone who might be a • Are you known as a team player or mentor? collaborator? You want to build relationships with anybody who • Are you considered trustworthy or respected has already traveled the road or who you could learn by your peers? from to avoid potholes or find a shortcut.
How Prepared are You to Move into a New Role? Hitting the Road
• Who could do your current job if you were Now that you know the road and have packed your promoted? bags, it’s time to start moving and charting your • Is there documentation of your work to help course. At this point, you need to be moving forward train someone else? so that you can grab the next opportunity that comes along. For this section, I will outline activities that I was doing to prepare for my first management Setting Your Course opportunity.
Once you better understand what you’re looking for There are two primary things that I did that I believe and how well prepared you are, it’s time to look out helped convince the decision makers that I was the window, analyze the landscape, and see who else ready to take my position to the next level (and lead is traveling on the road. This is also the time to con- others). First, I did a lot of sharing with my boss sider reaching out to others who can help you nav- and talked about my leadership and professional igate, give directions, or make repairs if something experiences and accomplishments. In my case, I unexpected occurs during the trip (and it’s likely had been a community STC leader (President of something will come up). Your goal here is to find Philadelphia Metro chapter) and presenter who the next opportunity, pull off, and grab that prime spoke at regional and national events (such as the spot before somebody else does. STC Summit). Additionally, I made sure that my manager knew that I was looking to advance in the Examine Your Surroundings company and was prepared to take an assignment or role that would help the company as well as further • What is the next promotion level for you? my professional goals (it wasn’t just about me).
2015 STC Technical Communication Summit Proceedings 53 Leadership and Management
Second, I documented and spoke about how I per- make sure the team is doing the job that is formed my job as a ‘department’ (of one)—writing expected of them. down duties and responsibilities. Since I was a lone • You are not an individual contributor. writer it was important to demonstrate that I was Although you may continue to have some able to self-manage and make decisions with little responsibility for line-level work, in most oversight or supervision. Of course I had to perform cases you will not be the one getting your and do solid work, but it was noted that I kept busy hands dirty, but you have to ensure the job and worked with little direction while handling gets finished (and may have to step in to do issues or getting past obstacles. While accepting it). additional responsibilities and asking for work, I stayed positive and enthusiastic, worked with other • You now are playing multiple roles. You’re teams, and maintained consistent standards. For not just the star actor anymore, now you’re example, I created a Tech Comm Style Guide and a director, camera person, editor, producer, documented my procedures in a handbook. screenwriter, and so on—you’ll be wearing multiple hats. So it’s important to document and share your expe- • You are the compliance checker and enforcer. riences so that others can appreciate that you’re a You have to make sure that you and the team seasoned and well-traveled driver—that your capa- follow company policy and implement the ble of handling the trip. This gives future decision goals and directives of upper management. makers and hiring managers confidence that you can It’s you that has to explain if the team breaks take the wheel in their organization and that you are a rule, doesn’t meet a deadline, or misses positioned to be a primary driver who is responsible something. for the well-being and safety of others (your future team). • You are a decision maker. You’re expected to have an answer or solution if somebody on the team has a question, isn’t sure what to do, Getting Your Bearings needs support, or doesn’t know how to do something. Congratulations! If you’ve been lucky enough to Basically, the responsibility, judgment, failures, and identify a management opportunity and given the successes of the team start and end with you. You keys to a a new role, it’s time to settle in and see how no longer are the one who gets the credit, but at the this management ride suits you. First things first same time you are expected to accept the responsi- though, as a new manager you need to focus on the bility for any missteps or mistakes made by you or a basics and learn the ropes before you become the member of the team. In the eyes of the organization, ‘boss.’ More importantly, understand that being a you are the last word. manager is different than being a sole contributor or member of a team—the buck now stops with you! So what does that mean? Deciding If It Fits I’ve said being a manager is different, but how is it different? There are plenty of books and other There will be times when everything is clicking (you resources that explain all the big and little differ- and the team are hitting all the notes) and then ences, so I’m just going to provide a few high-level there will be other times when you want Calgon to bullets to show you’re really not in Kansas anymore come take you away (if you’re dealing with personnel (or wherever your journey began). You’ll notice that issues or putting out fires)—that’s just the swing the items I list all start with the word ‘You’—that’s of being responsible for a team. You should expect not a coincidence. highs and lows and that the first few months of being a manager will have challenges that you didn’t • You are responsible for others. The work, anticipate. behavior, and effort of your team falls on you. It’s a big adjustment and difficult to prepare for • You are evaluated by the team’s performance. being a manager beforehand. Give yourself time to Your individual work or accomplishments learn the ropes, sort things out, and really work at are no longer the focus, so you have to the manager ‘job’ before you decide if it’s really the
54 2015 STC Technical Communication Summit Proceedings Becoming a New Manager
career path for you—if it’s a good fit, the experience Communication degree and is an active participant can be rewarding. and Senior Member of the Society for Technical Communication (including Past President of the However, there are people who become a manager Philadelphia Metro Chapter ‘of Excellence’ and and then realize that they prefer being in the 2014 recipient of the Distinguished Chapter Service trenches, aren’t comfortable with the added respon- Award). sibility, or dislike the extra overhead, politics, or paperwork. Regardless of the reason, it’s alright to Todd believes that service to others is a vital part of later find out that being a manager is not the right personal enrichment and a key component to pro- path for you (or not at this time). If that’s what you fessional advancement. He is actively engaged with later decide, trust your instincts, move on to the the STC community and enjoys learning, speaking, next opportunity, and consider being a manager and sharing his experiences with colleagues. Over just a step along your career journey (like any other the past two years he has presented multiple times at position). the STC Mid-Atlantic (Philadelphia), STC Spectrum (Rochester), and STC Summit conferences.
Taking It with You
Being a manager is a job, like any other—it takes work, dedication, practice, and commitment if you want to improve and eventually be good at it. Some people are more drawn or suited to it, but it can also be taught and learned (like any skill). Personally, I’m on my second full year and there are still days when I’m not sure if being a manager is the right path for me or I don’t feel very confident about my performance (but it’s a lot fewer days than in the beginning). Regardless of where I eventually end up, I’ve learned a lot about myself, and gained many new skills (leadership, collaboration, evaluation, commu- nication, and so on)—which I will take with me to the next stop in my career journey.
So go ahead, get your bags packed and hit the road! Keep an eye out for that next great opportunity to advance and lead others. When you find it, pull off and settle in for a while. You may just find that it’s just the place you didn’t know you were looking for.
Author Contact Information Todd DeLuca Manager, Technical Communications Black Knight Financial Services Chester Spring, PA (telecommuter) +1.484.885.9145
Author Biography
Todd DeLuca has 15 years of experience as a Technical Communication professional with a career that has led him from working as a solo writer (department of one) to managing a team of technical writers. He has a Master of Technical and Scientific
2015 STC Technical Communication Summit Proceedings 55 Leadership and Management
56 2015 STC Technical Communication Summit Proceedings 2015 STC Technical Communication Summit 21–24 June 2015 • Columbus, Ohio © 2015 Society for Technical Communication
SIMPLE SCHEDULING Mike Sawyer
For small- to mid-scale project tracking, spreadsheets exemplify simplicity and func- tionality. Spreadsheets are ideal for managing and presenting lists of information. This progression introduces Microsoft Excel tables, formulas, standard and conditional for- matting, sorts and filters, and sharing and archiving strategies for the information. For the latest version of this guide and other supporting materials, see bit.ly/simpleschedule.
s your workload too big for sticky notes but the • List your projects in the left-most column, Ibudget’s too small for a complex tracking tool? and project data fields along the top in a Learn how to use Microsoft Excel conditional non-scrolling heading row. formatting, tables, and formulas to list, sort, and • Small fonts are your friends. Narrow fonts automatically mark priority projects and track your are especially useful in keeping information progress. This ubiquitous tool can do more than compact. most of us realize! • For widescreen viewing and wide printing, This session covers spreadsheet layout for a doc define the page size as Legal (or a similar schedule, types of fields and data, formatting, helpful wide format). formulas, best practices, and on-the-cheap alterna- • Define the rows and columns as a data tive spreadsheet programs. table. This enables easy sorting and filtering (explained later). To define your list as a table, select the range of cells, then click Assumptions Table in the Insert ribbon.
The presentation assumes a familiarity with spread- • Define the first column as sequential row sheets in general, and Microsoft Excel in particular. numbers that don’t sort or change order with Resources are provided, though, for learning basic the rest of the data. This makes it easy to spreadsheet principles and alternatives to Excel. refer to row numbers when discussing the schedule with others. • To more easily work with printouts of the Layout schedule, create a header or footer that contains page numbers, print date, filename, Although you can design the sheet however you want, and file location. these are some guidelines I’ve used with success: • Although an Excel spreadsheet can have Column Titles (Fields) thousands of columns and over a million rows, try to keep your sheet narrow enough The fields you define as columns in your sheet will that it can print its full width onto a land- depend completely on your own job’s needs. If scape sheet. you are an internal department, your focus may be on product development schedules and related milestones. If you do work for external clients, you
57 Leadership and Management
may focus on tracking billable hours (and expenses). • Along with the familiar horizontal alignment You’ll get the clearest understanding of your needs formats, in cells you can set the vertical by first starting to use a prototype tracking sheet, alignment. For some reason, Excel aligns cell then modifying it as you go. Here are some fields to content at the bottom by default (who reads consider: from the bottom first?), so change that in any new spreadsheet by selecting the entire • Part number (or some unique identifier) sheet and clicking Top Align on the Home • Product name ribbon. • Code name (used until product name is • You can format a cell’s fill color, but you official) can also format its pattern (for a “shaded” look). Be conservative in applying fill color or • Deliverable type (user guide, brochure, pattern—what looks good on-screen may not online help, etc.) be readable when printed. And if you print • Priority only to black & white, keep that in mind when you’re selecting formatting for cell • Assignments (writer, editor, designer) shading (avoid shades of similar darkness, • Goals & gates: Draft due, final due, product for example). ship date • Try formatting text or shading to mark • Historical: Date entered/requested, date urgent projects with red, or completed proj- edited, date approved, date sent to press ects with green. • Time measuring: Elapsed time since start • To prevent long text from getting truncated (work days vs. true days), time left before at the cell’s border, select the entire sheet due. Hours (for billing), budget (hours or and click Wrap Text on the Home ribbon. money) • When using dates, use short date formats to • Cost: Budget planned, budget used, budget save room. Excel “remembers” the full date remaining (along with the year day of the week), even if the date format you select is a short “xx/xx” • Miscellaneous notes (often the widest field) version. • When using currency, use short currency Formatting formats to save room. Excel “remembers” the full money amount, down to whatever You’ll want the data to be dense, but readable, and fraction you specified, even if the currency you’ll want the significance of priority data to stand format you select is a shortened or rounded out. To accomplish this, you can use direct format- version. ting and conditional formatting. Conditional Formatting Direct Formatting Conditional formatting is “programmed formatting” You’re a technical communicator, so you’re already that’s applied automatically when certain conditions well-versed in basic text formatting. But there are are met. The “Starter Spreadsheet” available at bit. some quirks to Excel formatting to keep in mind: ly/simpleschedule contains examples that you can try out and copy. Conditional formatting is powerful, • You are the audience for this document, so and it’s fun to experiment with. use formats that work well for you. Examples: • You can edit selected characters/words within a cell, but it’s easiest to apply edits • Automatically shade a project’s Part Number to the cell as a whole. Think of cells as cell green when the project’s “Priority” col- mini-paragraphs; just click to select a cell, umn is marked “A.” then click a format on the Home ribbon to apply to the cell. • Mark the “Due” cell red if the date is less than a week away.
58 2015 STC Technical Communication Summit Proceedings Simple Scheduling
• Automatically draw a progress bar in back- of formulas and functions. Here are some of my ground of a “% Complete” cell to visually favorites: depict the number. • AVERAGE Computes the mean value of a To apply conditional formatting (this will be demon- range of cells. strated in the session): • CELL Can show the sheet’s filename. Useful 1. Select the cell(s) to apply the conditional for headers/footers. format to. • CONCATENATE Joins several text strings 2. On the Home ribbon, click Conditional into one text string. Formatting, then click New Rule. • COUNT Counts the number of cells within a 3. Select the rule type and parameters, then range that contain numbers. click OK. • COUNTBLANK Counts the number of empty cells within a range of cells. Sorting and Filtering • COUNTIF Computes the number of cells within the defined range that meet the crite- After you’ve defined the data as a table, sort buttons ria you specify. appear to the right of each column label. To sort on • MAX Returns the largest value in a set of any column, click its sort button, then select which values. order you want the data sorted by. • MEDIAN Returns the median value in a set You can also temporarily hide rows of data by using of values. a filter. To use a filter, click the column’s sort button, • MIN Returns the smallest value in a set of then select the rows to display or hide: values. • ROUND Rounds a cell’s fractional value to a Formulas and Functions specified number of digits. • SUM Adds all numbers in a range of cells. Formulas transform the spreadsheet from a record-keeping tool to a computing tool. Formulas Time functions: automate repetitive tasks and do math for you. You • DAYS360 Returns the number of days can think of formulas as equations—because that’s between two dates. Useful for counting days what they are, only these equations start with the “=” remaining before deadline. symbol. • NETWORKDAYS Returns the number of To enter a formula in a cell (this will be demon- “business days” (M-F) between two dates. strated in the session): • NOW Returns the current date and time, 1. Type the equals symbol (=), then type the down to the second. function name (such as AVERAGE). 2. After the function name, type the range in Best practices parentheses (if a range is required). 3. Press Enter. The formula disappears, and Although you should use whatever process works for the value it returns is displayed. you, here are some guidelines I’ve used with success:
When you type a formula into a cell, Excel “remem- • Create (and name with the date) a new copy bers” what you typed there, but it displays only the of the sheet (a “tab”) each week. result of the formula. “Functions” are terms you can • Name the sheets by date (for example, use within a formula to help it complete its computa- YYYY-MM-DD). tion (such as “MEAN” to compute the mean value of a range of cells). The “Starter Spreadsheet” available • Maintain at least one quarter’s history of at bit.ly/simpleschedule contains working examples sheets, archiving old sheets at the end of each quarter.
2015 STC Technical Communication Summit Proceedings 59 Leadership and Management
• Save a copy of the sheet each week, named Microsoft Office Support. “Overview of formulas.” by date, and store in a location that is backed Support.office.com (8 May 2015). support. up. office.com/en-ca/article/Overview-of- formulas-7abfda78-eff3-4cc6-b4a7- • Maintain a master project history separate 6350d512d2dc. from the doc schedule. The doc schedule itself is dynamic and transitory—it can Small Business Computing.com. “4 Free change daily, and projects can be removed Spreadsheet Alternatives to Microsoft Excel.” from the sheet as they are completed to Smallbusinesscomputing.com (8 May 2015). prevent the schedule from becoming cum- www.smallbusinesscomputing.com/biztools/ bersome.. A master project history records article.php/10730_3939366_2/4-Free- every project, when it was completed, and Spreadsheet-Alternatives-to-Microsoft-Excel. who completed it. It can also record where htm. the project’s files are stored, which revision is current, and what changes are requested Author Contact Information for the next revision. I only add to the master history when a new project begins and is Mike Sawyer completed. Documentation Manager Control4 • For recording work hours, consider record- 92 West 1565 North ing only the totals on your doc schedule, Orem, UT 84057 U.S.A. and keep the details to specialized time +1.385.209.7164 tracking software. (Recording individual, day-by-day hours in the doc schedule can result in numerous columns and an ungainly Author Biography worksheet.) Mike has 20 years of experience in technical docu- • If your company or department doesn’t mentation as an employee, freelancer, and manager. already use a part numbering scheme to He loves writing, editing, and designing, and also uniquely identify each project, start now. has a background in human factors engineering Unique part numbers simplify record keep- and ergonomics. He’s worked for WordPerfect/ ing and archiving in a big way. Novell, Gateway, and Linksys, as well as many smaller companies and clients. He likes organizing Additional Tips information and helping others, so is happy with his career choice. Before starting his writing career, he worked as a bag boy, cashier, fireman, and bank For a list of cheap/free Excel alternatives, search teller (but not at the same time). He graduated in online or see the list at on bit.ly/simpleschedule. See Communications Studies, minoring in English, at the same website for more tips on designing doc Brigham Young University. He completed course- schedules. work for his master’s in Human Factors Engineering at the University of South Dakota. Resources He’s lived in California, Idaho, Iowa, and Utah, and Sawyer, Michael D. “Simplified Scheduling.” served as a missionary in Japan for two years. He Sawyerhome.net (8 May 2015). www. has five kids, one wife, five cats, and two litter boxes. sawyerhome.net/stc/schedule.html. He considers himself wealthy, by litter box standards.
References
Excel Easy. “Formulas and Functions.” Excel-easy. com (8 May 2015). www.excel-easy.com/ introduction/formulas-functions.html. Tech on the Net. “MS Excel: ALL Formulas/ Functions.” Techonthenet.com (8 May 2015). www.techonthenet.com/excel/formulas/.
60 2015 STC Technical Communication Summit Proceedings 2015 STC Technical Communication Summit 21–24 June 2015 • Columbus, Ohio © 2015 Society for Technical Communication
COPYRIGHT LICENSING FOR REVIEW AND REUSE Dylan Tuttle
User-generated content is now commonly found in user documentation. Integrating user-generated content into structured or more functional documentation can be chal- lenging for the technical writer. Ownership and intellectual property issues can further complicate matters. Several legal strategies have been developed to limit liability. The technical writer needs to be aware of these issues not only to avoid potential conflicts but also to manage the relationship with their audience and other stakeholders. User accep- tance and participation can be improved with thoughtful use of copyright governance.
[Disclaimer: The following is intended for informational purposes only. It does not consti- tute legal advice. Consult an attorney if necessary.]
f you have ever edited a page on Wikipedia or writ- company to revise a clause that apparently gave Iten an answer on StackOverflow, then you prob- the company the right to sell your photos. The ably licensed your contribution under the Creative documentary Terms and Conditions May Apply has Commons Attribution-ShareAlike 3.0 Unported raised awareness of privacy issues, but ownership of license. This is consistent with the free culture goal content and the scope of copyright licenses are also of “creating a commons of freely reusable materials under scrutiny as can be seen on the website Terms that can be most readily used, shared, and remixed of Service; Didn’t Read. by others.” This may or may not have been your intent. In all likelihood you did this at your leisure The following list is a sample of issues monitored by and the consequences were benign if not beneficial. Terms of Service; Didn’t Read under the topics of Ownership and Scope of copyright license: As admirable as free culture goals might be, they may not be the best policy for you or your stakeholders. • Twitpic takes credit for your content Consider a scenario where you are basically soliciting • Google can use your content for all their users for product development ideas. Telling users existing and future services that their contributions are licensed under a free cul- ture license might elicit a skeptical response. Open • Couchsurfing keeps the license on your con- source software projects may be able to do this, but tent, even after you close your account even they are under increasing pressure to require • Couchsurfing becomes the owner of ideas contributor license agreements. This is often the you give them case for both code and documentation. • The copyright license in most terms of ser- Terms of service are an alternative to contributor vice goes well beyond the requirements for license agreements, but it is no longer safe to assume operating the service, often including subli- that users are oblivious to terms of service. A recent cense and perpetuity clauses. controversy over Instagram’s terms forced the
61 Leadership and Management
• One especially interesting clause in Early thinkers on the subject of the Internet, such Facebook’s terms states “We always appreci- as Ted Nelson, envisioned both read and write func- ate your feedback or other suggestions about tionality for the common user. Long before DITA, Facebook, but you understand that we may Nelson coined the term “transclusion.” His Project use your feedback or suggestions without any Xanadu envisions a system of micropayments for obligation to compensate you for them (just copyright protected works visibly connected by par- as you have no obligation to offer them).” allel pages. This might seem fanciful, but it serves as The fact that Facebook needs to make this a healthy reminder that there are alternatives to the explicit is telling. dominant design patterns. • It was 2004 when Tim O’Reilly gave his now famous Web 2.0 manifesto saying that “customers are building your business for Beyond the Firewall you.” Or as others have more cynically put it, “You are the product.” According to Google How can you benefit from improved copyright Trends, interest in Web 2.0 peaked in April governance? The two use cases that are probably of most relevance to the technical writer are review and reuse. In most cases you are probably behind a firewall. In which case, the intellectual property of all parties is typically assigned to the employer. Even in the case of independent contractors, the issue of intellectual property is usually covered by standard contracts. The status of intellectual property beyond the firewall is far more obscure.
Figure 1. Web 2.0 topic search, Google Trends Many popular business philosophies, including Lean Enterprise, Open Innovation, and Customer 2007. The last Web 2.0 Summit was in 2011. Development, require some degree of intellectual While not scientific, it seems safe to say that property sharing. This is often easier said than the Web 2.0 moment has passed. done. As in any relationship, equity will always be a concern. Appealing to abstract concepts such as In 2006 the UX expert Jakob Neilsen articulated “community” or “innovation” is as likely to alienate the 1% rule for participation inequality based on as inspire. Plain dealing is more likely to elicit a gen- earlier research by Will Hill. It basically states that uine response. While not always necessary, contracts you can only expect active participation from 1% of go a long way toward clarifying transaction terms. users. The general consensus appears to be that you may be able to skew the distribution, but you cannot Software developers are familiar with the code fight human nature. Rather than question the design review process. In the case of open source projects, pattern of social media and online communities, UX reviewers and even committers may be external con- experts appear more than happy to blame human tributors. Without contributor license agreements, nature and play what amounts to a numbers game. open source projects are exposed to liability and perhaps more importantly credibility issues with their customers. Increasingly we are seeing docu- mentation go through the same review process with the same agreements required from contributors.
Template agreements are available at Harmony Agreements’ website. They include contributor agreements for individuals and entities, and both license and assignment agreements. While the assignment of rights may seem desirable, you should note that many have found contributors unwilling to agree to assign their rights with obvious conse- quences for rates of participation. As in any contract,
Figure 2. OpenXanadu (sources only)
62 2015 STC Technical Communication Summit Proceedings Copyright Licensing for Review and Reuse
it is a question of fairness. Contracts are always The use case of templates is especially interesting. more or less favorable to each party. Templates can reduce effort while preserving rhe- torical freedom. They also do not require any special In addition to the issue of assignment, you would markup or processing. While there is nothing pre- also need to give careful consideration to the venting the free distribution of templates, there also outbound license. This is the license under which are no obvious incentives. Can a clear distinction the material contributed to is offered. It is often be made between reuse and republishing rights? At assumed that standard copyleft licenses such as what point does a derivative work based on a tem- those approved by Creative Commons or The Open plate become an original work? What is the differ- Source Initiative are the only option. This is clearly ence between a simple template such as a purchase not the case as we can see from the terms of service order and a generic document narrative? At what of various providers. The question then becomes point does the concept of authorship breakdown? why deviate from these apparent standards? These questions are the result of capabilities intro- The first question to ask is whether your use case duced by digital media. The potential of these new requires free distribution. Especially in the case of capabilities have not yet been fully explored. The media, you may want to reconsider the common technical writer is on the frontier of new media. Be wisdom that copyleft licenses are the best way to bold. promote your content when nothing prevents citing or linking to your content under standard copyright. This material is based upon work supported by the You are basically giving permission to republish, National Science Foundation under Grant No. IIP- which is not necessarily what you want in the case of 1416066. Any opinions, findings, and conclusions media. or recommendations expressed in this material are those of the author and do not necessarily reflect The second question to ask is whether reserving the the views of the National Science Foundation. right to republish would alienate your contributors. There is almost certainly a vocal segment that would not only be alienated but who would decry your cov- Resources etous ways. It would be critical at this point to keep in mind the principle of equity. Is the value you pro- Google Trends (1 May 2015). http://www.google. vide greater than or equal to the value you receive com/trends/ in contributions? If it is, then you can rest assured Harmony Agreements (1 May 2015). http://www. that participation inequality will not be a problem harmonyagreements.org/ regardless of your choice of license. Mader, Stewart. Wikipatterns (Indianapolis, Ind.: Wiley Publishing, Inc.), 2008. Georg Greve says of free software that “the expected return on investment comes in the form of strategic Project Xanadu® (1 May 2015). http://xanadu.com/ independence and lower licensing costs.” In opposi- Stim, Richard. Getting Permission, 5th edition tion to proprietary software, it is easy to understand (Berkeley, Calif.: Nolo), 2013. the appeal. It is far less obvious who the beneficiary Terms of Service; Didn’t Read (1 May 2015). https:// is when the customer is also the product. As Greve tosdr.org/ goes on to say, it depends on where you are in the stack. References Fortunately you are not obliged to use standard licenses. You could even write your own license. “Frequently Answered Questions.” The Open Source Whether evaluating terms of service, contributor Initiative (1 May 2015). http://opensource. license agreements, or standard licenses, you will org/faq want to consider the use case and how favorable the “Terms of Service.” Facebook (1 May 2015). https:// terms are for each party. Copyright governance will www.facebook.com/legal/terms impact your authorship model, which in turn will “Understanding Free Cultural Works.” Creative influence your design pattern. While not yet well Commons (1 May 2015). http:// understood, it is almost certain that participation creativecommons.org/freeworks can be improved if the principle of equity is applied to copyright governance.
2015 STC Technical Communication Summit Proceedings 63 Leadership and Management
Atwood, Jeff. “Attribution Required.” StackOverflow Author Biography (1 May 2015). http://blog.stackoverflow. com/2009/06/attribution-required/ Dylan Tuttle is no stranger to career change. He Derksen, Bryan, et al. “Web 2.0.” Wikipedia (1 started in the finance industry as a stock options May 2015). http://en.wikipedia.org/wiki/ trader. He then worked for a nonprofit workforce Web_2.0 development agency. In his most recent role, he was responsible for the development of a small business Greve, Georg. “What makes a Free Software training program. It was at this point that Dylan company?” freedom bits (1 May 2015). realized that training alone could not address the http://blogs.fsfe.org/greve/?p=260 need for improved knowledge management capabil- Hoback, Cullen. Terms and Conditions May Apply. ities. He is currently developing a web application 2013. to expand external working memory and improve Kaplan-Moss, Jacob. “Contributor License the ability to assimilate new information. It is Agreements.” Jacob Kaplan-Moss (1 an interpersonal wiki for informal learning and May 2015). http://jacobian.org/writing/ self-publishing. contributor-license-agreements/ Lemanski, Steve. “Technical Storytelling.” Intercom (June 2014): 7-12. Mason, Hugh, et al. “Instagram.” Wikipedia (1 May 2015). http://en.wikipedia.org/wiki/ Instagram Matthews, Charles, et al. “Wikipedia:FAQ/ Copyright.” Wikipedia (1 May 2015). https:// en.wikipedia.org/wiki/Wikipedia:FAQ/ Copyright Nielsen, Jakob. “The 90-9-1 Rule for Participation Inequality in Social Media and Online Communities.” Nielsen Norman Group (1 May 2015). http://www.nngroup.com/ articles/participation-inequality/ Reading, John, et al. “Web 2.0 Summit.” Wikipedia (1 May 2015). http://en.wikipedia.org/wiki/ Web_2.0_Summit Yerrick, Damian, et al. “Wikipedia:Copyrights.” Wikipedia (1 May 2015). http://en.wikipedia. org/wiki/Wikipedia:Copyrights Yerrick, Damian, et al. “Wikipedia:Ownership of articles.” Wikipedia (1 May 2015). http://en.wikipedia.org/wiki/ Wikipedia:Ownership_of_articles
Author Contact Information Dylan Tuttle Project Manager Vulkan Forge 10437 W Innovation Dr Ste 317 Wauwatosa, WI 53226-4843 +1.414.533.5687
64 2015 STC Technical Communication Summit Proceedings Copyright Licensing for Review and Reuse
2015 STC Technical Communication Summit Proceedings 65 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 2015 STC Technical Communication Summit 21–24 June 2015 • Columbus, Ohio © 2015 Society for Technical Communication
SMOOTHING THE TRANSITION TO DITA: EXPERT PARTNERS CAN EASE THE PAIN Nicki L Davis, Ph.D., Associate Fellow
Many companies are moving their content to DITA, a process that can be daunting for players who are new to such migrations and might not fully understand what they are getting into. In this practical, from-the-trenches presentation, you’ll learn from the expe- rience of a team of eight writers tasked with converting 10,000 pages of unstructured legacy content into structured (“intelligent”) DITA content. We describe problems encoun- tered and provide suggestions for making things go more smoothly. A critical factor in the success of the project was the use of expert partners for some tasks. The net result was clearer, more usable content and greater expertise for the writing team at a substantial savings over doing it all ourselves.
his session describes the experience of a team Project Initiation Tof eight writers who moved over 10,000 pages of technical content to DITA. A critical factor in the What problem were we trying to solve by moving success of the project was to hire the right partners to DITA? Here’s a brief description of our content for certain tasks. If you are considering a move to crisis: DITA, you can benefit from the knowledge we gained on when and how to hire expert partners. • Duplication of authoring efforts among different groups in the company, (training, The session describes all major phases of the project: technical support, and documentation) pro- duced overlapping content that was difficult 1. 1. Project initiation. Identify and address the to maintain. content crisis driving the need for content migration. • Content lacked standardization and consis- tency, making it difficult to share content 2. Content analysis. Assess the condition of among groups. existing legacy content and specify require- ments for the new system. • Device proliferation. We had to make sure that our content could be easily viewed on 3. Training and pilot. Develop expertise and mobile devices as well as in web browsers. create the necessary processes for working Most of our customers didn’t currently view with the new system. our content on mobile devices, but we knew 4. Content conversion, migration, and cleanup. that was coming soon. Not everything can be automated, but there are ways to minimize the amount of manual To solve these problems, we discovered eight tasks work required. for which we had no in-house expertise, so we got help for those tasks from outside partners (Figure 1). 5. Lessons learned. Takeaways for writers and managers. Because individual stakeholders (including our- selves) had only a limited grasp of the big picture,
67 Tools and Technology our first task was to obtain a detailed analysis of Writer Training and Pilot the problem from a neutral outside observer. Enter Partner #1. After we chose our CMS vendor, the next step was to train the writers in DITA and in the nuances of how to use the new CMS to create content. The training program consisted of two weeks of training on DITA and the CMS, followed immediately by a six-month pilot. During the pilot, Partner #2 helped us develop our information model, which is a specification of exactly which DITA features we needed to use, and how to use them. Partner #3 helped us to develop best practices for managing our content in the new CMS. Both partners were essential to the process of nailing down the innumerable details that were required to use a DITA-based CMS.
Figure 1. Eight tasks, four different partners On average, writers devoted about 20% of their time to the pilot. For our department of eight writers, the six-month pilot cost almost 10 months of writer time, Content Analysis but it was well worth it. The pilot was an essential “shakedown cruise” where we got to practice the Our work with Partner #1 gave us an excellent birds- knowledge we’d learned in the two weeks of training. eye view of our problems, a list of design goals to And, although we had known about DITA for a year solve them (Figure 2), and a consensus amongst the before the change, and some of us had even read stakeholders on where to go next. Significantly, a books about it, we discovered that there was no sub- consideration of our design goals revealed that our stitute for trying out DITA on our own content. existing topic-based content management system (CMS) did not meet our needs. Thus began our search for a new CMS vendor. Content Conversion, Cleanup, and Publication
Figure 3 shows the steps we used to transfer our content to the DITA-based CMS:
1. Export content from the old CMS. 2. Use a script to convert the proprietary XML from the old CMS to DITA. 3. Import the DITA content into an instance of the new CMS on a staging server. Figure 2. Bird’s-eye view of content problems and the design goals required to solve them
CMS Vendor Selection
After an exhaustive search, we found two vendors whose products met our requirements. Both prod- ucts required DITA. If we wanted the functionality we needed, we had to move to DITA.
To decide between the two products, the writing team evaluated each system for one week. The win- ner became Partner #3 on our report card (Figure 1). Figure 3. Content migration process
68 2015 STC Technical Communication Summit Proceedings Smoothing the Transition to DITA: Expert Partners Can Ease the Pain
4. Clean up the DITA content. performance of Partner #2 is particularly revealing. Although they did an excellent job at training us in 5. Transfer the cleaned-up DITA content to the DITA and helping us develop our information model, production server. they lacked the necessary expertise in script-writing. 6. Use scripts to publish the DITA content We saved money upfront by hiring them for script on the production server to PDF and to writing, but it worked out to be more expensive in different online output formats (HTML Help, the end. WebHelp, HTML pages, and so on). Our takeaways: Unfortunately, our collaboration with Partner #2 for conversion scripts did not work out well. As shown • On-site DITA training saved us countless in Figure 4, the conversion script could not distin- hours over trying to develop an information guish a step from a paragraph within a step, but also model and implement DITA after learning it duplicated the text. Because of the poor quality of from books or generic DITA classes. the converted content, cleanup required far more • Scheduling the six-month pilot project resources than expected. The consultant we hired immediately after training was an essential for the cleanup work (Partner #4) did an excellent step in getting us up to speed on DITA and job, but we unwittingly gave her more work than on our new CMS. The excellent support we she could complete during her six-month contract. got from the CMS vendor during the pilot Eventually, we had to spend more than two addi- was a major factor in the success of the tional years of writer time on cleanup. project. • When a partnership works well, you save time and avoid frustration. • Go for a partner with experience in the areas where you need help. Going with an inexpe- rienced partner can cost you years of writer time. • Even with the inexperienced partner, it was still worthwhile to get outside help. Figure 4. Typical example of content conversion • Don’t underestimate the complexity of writing scripts for content conversion and publication. What went wrong? To begin with, we probably overestimated the script-writing expertise of Partner • Manual cleanup is no fun. Take a look at the #2, a company that was primarily focused on DITA converted content in Figure 4 and imagine training. And we certainly underestimated the com- cleaning up thousands of procedures with plexity of writing conversion scripts. those defects.
Partner #2 did a slightly better job on the publica- tion scripts, but once again, we underestimated the complexity of the task. Surely, we thought, publish- ing from one standardized format (DITA) to another standardized format (PDF) would be a simple task. Not so! Subtle differences in DITA coding turned out to have unexpected consequences, particularly for PDF output. Eventually we had to hire a different contractor to fix the publication scripts.
Lessons Learned
The “Partner Report Card” in Figure 5 summarizes Figure 5. Our partnerships worked very well—with two the successes and failures of our collaborations. The exceptions
2015 STC Technical Communication Summit Proceedings 69 Tools and Technology
References of the Association for Computing Machinery, the User Experience Professionals Association, and the Davis, Nicki. “Case Study: The Value of Partnership American Chemical Society. during Conversion.” Data Conversion Laboratory, Inc. (18 June 2014) http://www.dclab.com/webi- nars/case-study-the-value-of-partnership-during- conversion.
Author Contact Information Nicki L. Davis Senior Technical Writer Complete Genomics, Inc. 2071 Stierlin Court Mountain View, CA +1.510.333.0875
Author Biography
Nicki Davis began her career as a technical writer while studying for her Ph.D. in chemistry. Dismayed by the poor usability of the analytical instrument that she and her fellow graduate students needed for their thesis research, she solved the problem by writ- ing a user manual. Inspired by this experience, she resolved to use her communication skills to make technology easier to use. Upon earning her Ph.D., she got her first job as a junior technical writer at an engineering company. After that position ended, she had a brief stint as a lab chemist, but quickly moved back to technical communications. Her job titles over the years include Scientist Writer, Senior Scientist Writer, Advisory Technical Communicator, and Senior Technical Writer.
Throughout her career, Nicki has focused on sav- ing customers’ time and money through effective technical documentation driven by usability. While working as a technical writer at a company that made software for chemists in the pharmaceutical industry, Nicki shifted her focus to user interface (UI) design, conducting usability tests and field stud- ies to find out exactly what users needed. At her next job, she initiated usability testing and made signifi- cant contributions to the usability of the company’s server products. Nicki has delivered several STC presentations based on her work in the field. At her current position at Complete Genomics (Mountain View, CA), she looks forward to making it easier for scientists to get their work done.
Nicki has received the Berkeley STC chapter Distinguished Chapter Service Award is an STC Associate Fellow. She is also a long-time member
70 2015 STC Technical Communication Summit Proceedings 2015 STC Technical Communication Summit 21–24 June 2015 • Columbus, Ohio © 2015 Society for Technical Communication
CAN LIGHTWEIGHT MARKUP PUNCH ABOVE ITS WEIGHT? Raymond Gillespie
Lightweight languages are easy to learn, easy to read, and easy to write. Should pro- fessional technical communicators working on existing large, complex documentation sets adopt lightweight approaches? To try and answer this question, I took an example document created using Darwin Information Typing Architecture then tried to recreate it using a lightweight approach: reStructuredText with Sphinx. I found that reStructured- Text/Sphinx provides good mechanisms for logically arranging and linking topics. Its ease of use—like with other lightweight languages like Markdown and AsciiDoc--makes reStructuredText an attractive option for projects where a lot of content input from soft- ware developers, system architects and testing engineers is needed. However, reStruc- turedText’s lack of distinct topic types and semantic tagging weighs against it being a suitable choice for many large-scale documentation projects.
n recent years many documentation teams have First using a semantically-rich markup language Ishunned the use of semantically-rich languages (DITA published using the DITA Open Toolkit); such as DocBook and Darwin Information Typing second using a lightweight markup language Architecture (DITA) in favor of lightweight markup (reStructuredText published using the Sphinx docu- languages such as Markdown and reStructuredText. mentation framework). By comparing the results, I Lightweight languages are easy to learn, easy to will present some pros and cons of using lightweight read, and easy to write. They are especially popular markup languages versus semantically-rich lan- in the realms of open source and Web-application guages for documenting large, complex projects. development, particularly with newer startup com- panies where the documentation is often created by But before describing this experiment and examining the developers themselves. By using a lightweight the results, let’s define what we mean by ‘lightweight language, developers can create and manage markup’. What are lightweight markup languages good-looking documentation using the text editors used for? What problems were they designed to and file-versioning tools they are already familiar solve? with.
But what about professional technical communica- What is Lightweight Markup? tors working on existing large, complex documen- tation sets? Should we follow this trend? Should we John Gruber, the creator of Markdown—probably throw away our fancy XML editors, our DTDs, our the most popular lightweight markup language— Content Management Systems, and go lightweight? described his creation as:
To try and answer this question, I performed an “…a plain text formatting syntax…a software tool…that experiment. An experiment where I created two converts the plain text formatting to HTML.” versions of the same example topic-based document.
71 Tools and Technology
We can apply this definition to lightweight markup Figure 1—indent each line by at least 8 char- languages in general. Whether we are looking at acters (2 tab stops). reStructuredText, or AsciiDoc, or Markdown itself, • Inline code. Wrap inline code with backtick what these languages all have in common is that they characters (`). have a plain text formatting syntax, and they come with software tools to convert that formatted text to The important thing to note is that even without HTML. And increasingly these software tools—often the colored syntax highlighting and live preview referred to as ‘toolchains’—can convert the plain provided by the MarkdownPad2 editor, the actual formatted text to other formats, such as PDF and Markdown text is easy to read. You can open it in the even XML. simplest of text editors—like Windows Notepad or Mac TextEdit—and it will be perfectly readable and The quickest way to get the gist of a lightweight easily editable. language such as Markdown is to try it for yourself. For Windows users, a good tool to start with is the free version of the MarkdownPad2 editor (a similar How Did Lightweight tool for the Mac is Mou and for Linux ReText). The nice thing about MarkdownPad2 is that its 2-pane Markup Come About? interface shows your plain text in the left pane and a preview of your rendered HTML in the right pane. I would argue that there are two historical drivers Figure 1 shows an example Markdown document that led to the development of lightweight markup. typed into Markdownpad2. First, there is a long history of formatted plain text. Since the early days of computing, content creators This example shows some of the available Markdown have made use of informal methods—such as under- syntax: lining headings with dashes, and using asterisks to indicate bullets—to add some structure to their plain • Headings. Precede your heading with hash text documents. Second, the arrival of the World marks; one hash signifying heading level 1, Wide Web brought a need for fast, simple alterna- two hashes heading level 2 and so on. tives to hand-coding HTML. Lightweight languages • Numbered list. Precede each list item with such as Markdown [1] reStructuredText [2] and a number followed by a full stop. AsciiDoc [3] were developed to meet that need. • Code block. Indicate code blocks by indent- ing each line by at least 4 characters (com- monly 1 tab stop). In the case of a code block within a numbered list—like that shown in
Figure 1. A step-by-step procedure written in Markdown
72 2015 STC Technical Communication Summit Proceedings Can Lightweight Markup Punch above its Weight? The Experiment: One For this experiment I chose to use reStructuredText Document, Two approaches as my lightweight language in conjunction with the framework tool Sphinx—the same combination used for the Python programming language documenta- From my first exposure to a lightweight markup tion [5]. language—to Markdown—I was hooked by the refreshing simplicity of a lightweight approach. But I So, let’s go through each of the five features and see wanted to see how such an approach compares with how the chosen lightweight approach shapes up. one of the documentation approaches I am more familiar with, for example with DITA. Is a light- weight approach really up to the kind of complex Mechanism for Logically Arranging documentation jobs I’m used to—where large doc- and Linking Topic Files umentation sets for products with multiple parallel maintenance releases are the norm? DITA maps provide a simple means for organizing your topic files into the structure you want (Figure 2. What I decided to do was create an example docu- DITA maps allow us to create a topic hierarchy2). In ment using DITA, and see whether I could recreate the words of JoAnn Hackos: it using a lightweight markup language. Although the sample document would be small, I decided that “DITA maps are the backbone of DITA. Maps provide it should at least test the lightweight approach’s a mechanism for ordering topics and creating a topic support for the following five features of DITA that I hierarchy.” [4] consider to be particularly useful for large, complex document sets: In order to logically arrange a set of reStructured- • Mechanism for logically arranging and link- Text files, and to provide basic navigational links ing topic files between the topics, we need a framework. And that framework is provided by Sphinx. Using a Sphinx/ • Support of distinct topic types reStructuredText approach, the equivalent to the • Basic reuse DITA Map is the ‘master document’, by default named index.rst. In the master document file, you • Mechanism for including metadata define a table of contents tree—in reStructured- • Semantic tagging Text parlance a toctree ‘directive’—comprising the sequence of files you want to include in your For the actual test document, I created—using the document. However, the toctree allows only a flat Oxygen XML Editor tool--a simplified version of the sequence of files to be specified. So to recreate example ‘Comstar User Guide’ that JoAnn Hackos the topic hierarchy of the example document, one uses in her book Introduction to DITA [4]. I then option would be just to abandon the separate topic attempted to recreate this user guide using a light- files and include, for instance, a concept and its weight markup language. related tasks in a single file. However, since I didn’t want to abandon the use of separate topic files at the first hurdle, I utilized another reStructuredText
Figure 2. DITA maps allow us to create a topic hierarchy
2015 STC Technical Communication Summit Proceedings 73 Tools and Technology
directive: the include directive which allows a file to looked up quickly by the user. By having distinct be included inside another file (Figure 3. Using the topic types—each with their own subset of markup reStructuredText toctree and include directives to tags—it makes it easy to maintain a consistent create a topic hierarchy3 and Figure 4. An example look and feel across large document sets. This is HTML page created from two reStructuredText topic particularly important for large-scale complex files using the include directive directives to create a projects where content might be created by multiple topic hierarchy4). technical communicators and where the users need consistency in order to find the information they Of course, if later we wanted to restructure our need quickly to perform their tasks. The Sphinx/ document, or reuse some of the parent topics in ReStructuredText approach offers no equivalent other master documents, some manual maintenance to DITA’s distinct topic types—when you open up of these include directives would be required. On a your text editor and start writing a topic there is small project, this would be trivial, but could become no structural guidance, you are free to use any of prohibitive on larger projects. ReStructuredText’s markup and directives.
Distinct Topic Types Basic Reuse
Another feature of DITA useful for complex docu- Content reuse mechanisms offer possibilities to mentation is its support of distinct topic types. The reduce the complexity and volume of our docu- three basic topic types allow us to create task topics mentation. DITA provides a rich choice of reuse to answer “How do I…” questions, concept topics options—including sophisticated mechanisms for to answer “What is this about?” questions, and transcluding content from dedicated reuse files, and reference topics to provide information that can be for conditional processing. But for this experiment, I
Figure 3. Using the reStructuredText toctree and include directives to create a topic hierarchy
Figure 4. An example HTML page created from two reStructuredText topic files using the include directive directives to create a topic hierarchy 74 2015 STC Technical Communication Summit Proceedings Can Lightweight Markup Punch above its Weight?
wanted to see if Sphinx/RestructuredText can repli- been built as HTML—including ones that were cate DITA’s simplest reuse mechanism: topic reuse. not referenced via the master document toctree or related include directives. In other words, I was gen- To do this in my DITA document was straightfor- erating HTML for some topics that I didn’t want to ward. I simply created a new DITA map, and added include in my new document (Figure 7). So a cleaner topicref tags pointing to the topics that I want to and more satisfactory solution was to create a new reuse (Figure 5. Reusing topics in different DITA source directory for the new project, copy the files I maps5) wanted to reuse into this directory, and then create a new master document. Having seen earlier how we could use the Sphinx/ RestructuredText master document to arrange topic I concluded that that Sphinx master documents are files in a similar way to how we use a DITA Map, not really intended for topic reuse and are clumsy to it seemed logical to me that we could use master use for this purpose in comparison to DITA maps. documents for topic reuse purposes. So I created a new master document in the directory containing the source topics I wanted to use, gave it a new name, Metadata and used this to generate a new document. With some minor changes to the Sphinx project configu- In the book “DITA Best Practices”, Laura Bellamy ration file (conf.py) it was straightforward to create and her co-authors state: a new document that reused some of the previously created topic files (Figure 6). “Metadata is one of the best ways to improve the retrievability of your information for both users of However, a look at the directory containing the your products and for your writers.” [6] HTML output of the Sphinx build process revealed that all of the .rst files in the source directory had
Figure 5. Reusing topics in different DITA maps
Figure 6. An attempt to reuse topics using a reStructuredText master document 2015 STC Technical Communication Summit Proceedings 75 Tools and Technology
One of the main mechanisms in DITA for including by back ticks. But in effect, all we are doing is tagging metadata is the element. This topic-level these items with formatting information. In contrast, element provides a container for topic-level meta- with DITA tags, we can distinguish between com- data. For example, you can place keywords for your mand names, variable names, user input values and topic within the container which will much more. And we can make use of this informa- render as keywords in the metadata of your HTML tion in our DITA deliverables. For example, we can output. use styling to differentiate user interface elements and so on. For the purpose of the experiment, I wanted to see if keyword metadata can similarly be added to reStructuredText’s lack of semantic tagging can also a reStructuredText topic. And the answer is that it make it more difficult to create consistent step-by- can. In reStructuredText you use a meta directive step procedures and reference topics. In the case of a to define metadata such as keywords to be rendered step-by-step procedure, a writer using a good DITA as HTML metadata (see Figure 8. reStructuredText editor can use the tags available in the standard topic file with metadata8). DITA topic task as a template. The basic topic task provides tags for task prerequisites, post requisites, examples within steps, and many other content Semantic Tagging structures that your task may need. And the editor will ensure that you put these tags in the correct Like the other lightweight languages AsciiDoc and place, greatly helping with consistency. Markdown, reStructuredText lacks the semantic richness of DITA. For example, with reStructured- With reStructuredText on the other hand, you are Text, we can mark up code elements, commands, commonly faced with a blank page and a much more filenames, and user interfaces by surrounding them limited set of markup tags with which to fill that page.
Conclusions
So, should you use a lightweight approach for your next project?
What struck me about reStructuredText—like with other lightweight languages like Markdown and AsciiDoc—is its ease of use. A big advantage of such lightweight approaches is that their simplicity makes them more likely to be used by our non-techcomm Figure 7. Rendered HTML from the reStructuredText topic colleagues. Collaboration between software develop- reuse experiment. ers, architects, testers and the technical communica-
Figure 8. reStructuredText topic file with metadata 76 2015 STC Technical Communication Summit Proceedings Can Lightweight Markup Punch above its Weight?
tion team can become easier. Since we are asking our [2] “reStructuredText” docutils-sourceforge http:// colleagues to write, edit and comment using plain docutils.sourceforge.net/rst.html (accessed text, they can use whatever text editor they use for April 3, 2015) their software creation tasks. And what’s more, the [3] “AsciiDoc Home Page” methods http://www. same versioning tools, the same review tools, the methods.co.nz/asciidoc/ (accessed April 3, same issue-tracking tools might be used for both 2015) software and documentation. [4] Hackos, JoAnn. Introduction to DITA, Second But the seductive simplicity of lightweight markup Edition (Denver, CO: Comtech Services, Inc.), comes at a price. They are semantically poor. For 2011 example, the basic Markdown language is little more [5] “Sphinx Python Documentation Generator” than a shorthand for a subset of HTML. The lack of sphinx-doc. http://sphinx-doc.org/index. distinct topic types also makes it more difficult to html (accessed April 3, 2015) maintain a consistent look and feel across a docu- [6] Bellamy, Laura, Michelle Carey and Jenifer ment set, especially in products where the documen- Schlotfeldt.DITA Best Practices: A Roadmap tation might be written my many different contrib- for Writing, Editing, and Architecting in utors from across the organization. In addition, the DITA (Upper Saddle River, NJ: IBM Press), lightweight approaches I have looked at so far do not 2012 lend themselves easily to content reuse.
I conclude that lightweight languages such as Author Contact Information reStructuredText offer an attractive option for Raymond Gillespie projects where a lot of content input from non-tech- R&D System Verification Engineer comm colleagues is needed. However, at least in Nokia Networks the case of reStructuredText, a lack of distinct topic [email protected] types and semantic tagging weighs against it being a +36 30 411 1516 suitable choice for many large-scale documentation projects Author Biography I would like to thank Dr JoAnn Hackos for her kind permission to use example DITA topics from her Raymond Gillespie, an STC Senior Member, has 20 book Introduction to DITA. [4] years’ experience in the field of information tech- nology. For the past 14 years, Raymond has lived in Budapest, Hungary working as both a software engi- Resources neer and a technical writer, mainly in the fields of telecommunication, medical imaging and navigation Deza, Alfredo. “Easy and beautiful documentation software. He currently works for Nokia Networks as with Sphinx” ibm.com. http://www.ibm. an R&D System Verification Engineer and has a spe- com/developerworks/library/os-sphinx- cial interest in the testing of procedural documents. documentation/ (accessed April 3, 2015) “MarkdownPad” markdownpad http:// Raymond holds an MSc in Information Management markdownpad.com. (accessed March 13, from Lancaster University Management School (UK). 2015) “Mou” 25.io http://25.io/mou. (accessed March 13, 2015) “ReText” sourceforge http://sourceforge.net/p/ retext/home/ReText/. (accessed March 13, 2015)
References
[1] “Markdown” daring-fireball.http://daringfireball. net/projects/markdown/ (accessed April 3, 2015)
2015 STC Technical Communication Summit Proceedings 77 Tools and Technology
78 2015 STC Technical Communication Summit Proceedings 2015 STC Technical Communication Summit 21–24 June 2015 • Columbus, Ohio © 2015 Society for Technical Communication
GIT STARTED: HANDS-ON GIT FOR AGILE WRITERS Sarah Kiniry
During the production process, performing basic command line tasks can be vital for Agile writers. Understanding the basics of Git™, a version-control software, allows writ- ers to view in-production changes and update UI text. By performing these tasks on your own, you will save time and energy, ensure quality text in your product, and get “mad technical props” from your developers.
What Is Git? as simple as entering text (a command) and pressing the Enter key. About a decade ago, Linus Torvalds developed Git for use by Linux kernel developers (Chacon, 2009). Since then, Git has become one of the most popular Data in Git version-control softwares available. It is widely used both by the open-source community, and by major Git stores the canonical set of data for any given corporations. Its popularity continues to grow, in project in a database, known as a repository. Each part, simply because it is already popular, with repository includes an object store and an index: copious resources available for anyone with a search engine and the desire to use it (Stephen, 2015). • The object store contains the project’s actual files (in the Git world, “blobs” and “trees”) In the simplest terms, version control software is and the records for each change that has software that manages changes to a collection of been made to those files (“commits,” each data (Chacon, 2009). This management is vital to identified by a SHA1 value) (Loeliger, 2012). large projects undergoing concurrent development • The index records the directory structure for by multiple teams. Version control software mit- all of the files in the object store (Loeliger, igates the risk of inevitable conflicts, and ensures 2012). that changes to one section of a file do not overwrite changes in another section. In addition, Git and To work with a repository’s data, users run the ‘git other systems like it provide change histories, store clone’ command from the CLI on a local computer copies of each file and its revisions, and maintain file that has Git installed. This command copies (clones) and directory structures. all of the supplied repository location’s data and creates a new directory within the working directory. It is important to note that, before writers can The new repository that you have copied contains successfully work in Git, they should have at least a all of the same files as the source repository, but will basic grasp of the command line interface (CLI). The maintain its own unique history when changes are CLI allows users to run text commands that trigger made (Loeliger, 2012). actions in a computer program. Working on the CLI may seem daunting to first-time users, but is actually
79 Tools and Technology
Branches ency with the team. A regression into waterfall, with the writer excluded from the team’s development The ‘git branch’ command creates “branches.” process, is to be avoided at all costs. Branches are copies of the cloned main repository Using the ‘git checkout’ command, users switch quickly between multiple branches of the same project. This is a particularly useful feature for writers who generate content for several lines of development at once, or who may need to compare the functionality of a branch that is in a known state with that of a team branch.
Multi-Team Development Figure 1. Two of the many possible branch structures for an Agile team.
that are used to make and test changes, and then merged into the main repository. Changes that you make in a branch will not affect the main repository until you intentionally merge them (Loeliger, 2012). Each branch includes the entirety of data in the main repository. Figure 2. A complex Git structure, possibly for a product Some teams prefer to maintain separate branches with many Agile teams or separate projects. for different areas of development (for example, a team might have separate branches for backend Once changes are merged into the main repository, development, testing, and text changes). This offers other users or teams can access and update the the benefit of allowing development to happen changed files, or merge these changes into existing independently of low-impact text changes, and can branches. This allows for simultaneous development be expedient when working toward a close deadline, by any number of users or teams, because users can or when working on a particularly difficult-to-test work in close proximity without the fear of overwrit- project. However, if the entire team does not ing each other’s work. maintain awareness of all branches of development, this method can unfortunately result in the writer Git has the capacity, too, for more elaborate becoming sidelined. It may also cause some areas structures. Individual teams might have multiple of development to fall behind others, since new branches or their own repositories for different proj- changes will need to be merged into each branch ects or releases of a product, all coming from one from the team repository separately. main repository.
On other teams, writers may work within, and com- mit changes to, the same branch as the team’s devel- Git Archaeology opers. This structure ensures that the writer’s work is transparent to the rest of the team, and is treated Though of course it was created with software devel- as a fully-qualified part of the Agile process. It also opment in mind, Git’s functionality isn’t only useful ensures that the branch is as up-to-date as possible to software developers. It is also extremely advanta- with regards to new changes. It requires additional geous to technical writers who work as members of diligence from the writer, however, to ensure that Agile teams. changes do not lag behind or hinder development or testing, impacting the team’s overall workflow. • Changes are accessible by everyone on a team, generally in near-to-real time. Many writers may find it useful to work in a combi- • Writers have the tools to engage in their own nation of these two options, to tailor workflows to “archaeology.” the needs of the work. In either scenario, of course, the most important part of the process is transpar-
80 2015 STC Technical Communication Summit Proceedings Git Started: Hands-On Git for Agile Writers
• Writers can update interface text or make Git Blame other changes directly, before development finishes. The ‘git blame’ command drills down into the current state of an individual file in the repository • Git acts as a sort of technical training ground, (Loeliger, 2012), and displays each line of the file’s ensuring that writers get the chance to spend current state. For each line in a file, Git displays a time in the code and better understand their shortened form of the commit’s SHA1 value, the product from the inside out. committer’s name, the date and time of the change, Git’s archaeological tools allow writers to perform and the line number. The commit ID can be used their own investigations of changes, sometimes with- with the ‘git log’ command to find more information out needing help from teammates at all. This frees about other changes in that commit. up valuable time that was previously spent “chasing down” information, and provides technical data in a much richer context.
Git Diff
The ‘git diff’ command compares files between two specified commits, and outputs a line-by-line listing of all of the changes that occurred between one point Figure 4. An example of the ‘git blame’ command and its in time and another (a “diff”). This command is very output. similar to the ‘diff’ program (Loeliger, 2012), and is, perhaps, the most useful archaeological tool in Git. The attribution information that it displays for the last commit in which each line changed is especially useful if the date or source of a change is unknown. For example, in more elaborate Git repository struc- tures with multi-team development, the ‘git blame’ command can help to distinguish between changes
Figure 3. An example of the ‘git diff’ command and its output.
The fact that the two commits need not be sequential Figure 5. Some possible uses of the ‘git log’ command and allows comparisons to be made not only against its many options. recent development, but also against previous points in time. Agile writers are likely to use this command often, to find the diff of changes for a given devel- from a writer’s own team and changes from other opment period, or even the changes made in a given teams that have been merged into a working branch. workday.
For example, if a writer knows the last commit GIT LOG at which a document was updated, running a diff between that commit and the current commit will Run without options, the ‘git log’ command displays reveal all of the possible changes to functionality that a list of the commit information for every commit in need to be included in updates to that document. the current repository or branch (Loeliger, 2012). This becomes even easier for updates to documen- tation for versioned software, if all of the major This command is more helpful when used with addi- versions are available to compare. tional options, of which it has an extensive list. • Providing a specified number of commits will display a pared down list of only the most
2015 STC Technical Communication Summit Proceedings 81 Tools and Technology
recent commits. Often, it is only necessary to might, however. The ability to read the code and view the most recent log entry. find specific landmarks, particularly comments and printed text, is far more important than the ability • Running the command with a specific to write even a small script or function. Writing commit’s SHA1 value (perhaps as retrieved functional code is even more helpful, of course, but it from the ‘git blame’ command) displays the shouldn’t be considered a prerequisite by any means. information and commit message for that specific commit. The usefulness of Git, of course, only goes as far • When run with a specified filename, the as the individual writer’s ability to work in it inde- command displays only the commits that pendently. Luckily, this is a tool that you can practice changed that file. in easily:
• Other useful options include limiting the list • If you have access to your company’s code- to commits by a certain author, before or base, pick a previous change to research, and after a certain date, or options that modify practice following the inevitable rabbit trails the information displayed for each commit. through the code and Git’s history. • If you don’t have access to a production codebase, repositories can be created on your local computer, or on repository hosting ser- vice sites like the extremely-popular GitHub. Figure 6. A ‘git log’ entry for a single commit.
• The ‘git log’ command’s one failing as Resources an archaeological tool is that it generally depends on the commit message to provide Olsson, Aske and Rasmus Voss. Git Version more detailed information. Because each Control Cookbook (Birmingham, UK: Packt committer writes his or her own commit Publishing), 2014. message, this message is not always all-in- clusive or even particularly helpful. References
Best practices state that commits should include a Chacon, Scott. Pro Git (New York, NY: Apress), short summary, followed by a detailed explanation 2009. of the reason for the change and its effects (Chacon, Loeliger, Jon and Matthew McCullough. Version 2009), but these guidelines aren’t always followed. Control with Git (Sebastopol, CA: O’Reilly), In most cases, however, it should provide introduc- 2012. tory information, and the name of the committer to ask if more detailed information is needed. Stephen. “The Case for Git in 2015.” ‘Net Instructions (20 Jan. 2015). http://www. netinstructions.com/the-case-for-git/ Hands-On Changes Author Contact Information A basic understanding of Git opens the door for Agile writers to make and commit their own changes Sarah Kiniry to a software project’s UI text, or other small text Technical Writer II changes. For example, rather than relying on devel- cPanel, Inc. opers to update text to Global English standards 3131 W Alabama Ste 100 after development, a team’s writer could use a Houston, TX 77098 simple text editor and Git to commit all of the tex- +1.713.742.3617 tual changes iteratively, as part of the development process. Author Biography
Of course, the ability to do this relies on having some Sarah Kiniry is a Technical Writer for cPanel, Inc., familiarity with the coding language in which the a web hosting software company. In this role, she text is embedded. Writers do not need to approach provides full documentation support for an Agile this in the same way that a beginning developer
82 2015 STC Technical Communication Summit Proceedings Git Started: Hands-On Git for Agile Writers
development team, as well as participating in con- tent strategy and other initiatives for the company as a whole.
Recently, she spearheaded a project to completely rewrite the company’s extensive SDK documenta- tion, including new documentation for six separate APIs with a combined total of over 1,000 separate functions in multiple coding languages, as well as new documentation for other proprietary integration systems.
In a past life, Sarah was a stage manager and audi- ence development manager at several of Houston’s professional theaters and performing arts venues. She believes that technical communication is really just another performing art, and that documenting an interface isn’t that much different from telling any other story.
You can read more about Sarah’s journey into soft- ware documentation at technicolorwriter.com.
2015 STC Technical Communication Summit Proceedings 83 Tools and Technology
84 2015 STC Technical Communication Summit Proceedings 2015 STC Technical Communication Summit 21–24 June 2015 • Columbus, Ohio © 2015 Society for Technical Communication
ITERATIVE DEVELOPMENT MODELS AND PROCESS IMPROVEMENT Tina M. Kister, PMP
All healthy information design processes are iterative, and having a deeper understand- ing of iterative development models across industries provides valuable insight into tech- nical communication processes. There is a surprising similarity across industries, and an analysis and comparison of both scholarly and non-scholarly sources reveals that several elements are universally important.
here are two basic types of development models: care, and more. (See the section titled Development Tsequential and iterative. Often, new development Models Across Industries for a list of examples.) models are presented in opposition to older models, which are criticized for being too sequential and A comparison of models across industries reveals not iterative enough. A close examination, how- that three primary phases are universally important: ever, reveals that even those development models generally presented as sequential contain iterative • An initial phase for gathering information phases, and were originally intended as guidelines and planning that should be adapted for specific requirements and • A design and development phase situations, rather than implemented in a rigid way. This false opposition is indicative of a novice-level • A phase or multiple phases for testing, approach that can lead to decreased quality and review, and refinement efficiency.
The successful application of development models Types of Development Models requires an expert-level understanding that facili- tates flexibility and adaptation. Applying develop- There are two basic types of development models: ment models with this approach can lead to substan- sequential and iterative. Sequential development tial process improvements. models are characterized by a more linear approach; that is, it is generally accepted that one phase must be complete before the next phase begins. Iterative development models, in contrast, are characterized Development Models by repetition and revision. Iterative models explicitly Across Industries provide “for changes in requirements and design as the project progresses.” [1] A development model is a conceptual representation of the processes used to create a target product, Sequential and iterative models are often presented condition, or other deliverable. Development mod- in opposition to one another in order to highlight the els exist for a wide variety of fields and industries, advantages of one over the other. including software development, instructional design, design and innovation, social change, project management, land management, engineering, health
85 Tools and Technology
Two Opposing Models in is often cited as a source of the Waterfall methodol- Software Development ogy, [4] reveals that the intended spirit, while well- planned, top-down, and highly monitored [5] was Two archetypal examples of sequential and iterative also highly iterative. “We had a need to… recognize development models related to software develop- that things would not work well the first, second, or ment are Waterfall and Agile, respectively. A typical third time, and therefore that much independent graphic depiction of the Waterfall development testing was needed in successive phases; to create model appears very linear. Often, graphic depictions development tools that would help build products of this model do not visually indicate any iterative and test tools and to make sure they worked…” [5] stages. In fact, Benington warned against taking an approach that is too sequential: “The great majority [of descriptions of programming processes] seemed to espouse the following approach: we must write the initial top-down specification (for example, the A Spec), then the next one (typically, the B Spec), so we will know precisely what our objectives are before we produce one line of code. This attitude can be terribly misleading and dangerous.” [5]
The iterative nature of Benington’s early work is evi- dent in the diagram depicting program production at MIT’s Lincoln Laboratory in the 1950s.
Figure 1. Waterfall Development Model [2]
In contrast, a typical graphic depiction of the Agile development model appears explicitly cyclical.
Figure 3. Nine Phases in Preparing a Large System Program [5]
Figure 2. Agile Development Model [3] Two Opposing Models in Instructional Design
A closer examination, however, reveals that the Within the field of instructional design, two other apparent dichotomy between these two models is development models are being presented in a similar often overstated. A retrospective written by Herbert oppositional relationship: the Instructional Systems D. Bennington, one of the authors whose early work Design (ISD) model, which has evolved into the 86 2015 STC Technical Communication Summit Proceedings Iterative Development Models and Process Improvement
widely-used Analyze, Design, Develop, Implement, more creativity, and addressed effective stakeholder Evaluate (ADDIE) [6] model, and the Successive involvement.” [10] Approximation Model (SAM). [10] A closer examination, however, reveals that both the In 2012, Michael Allen, an industry leader in original ISD model and ADDIE are highly iterative instructional design, published a book called Leaving and designed to be adapted to specific situations. ADDIE for SAM: Faster, Better Learning Product The original ISD model, based on work conducted in Development. Allen’s stated goal was to develop the 1970s at Florida State University for the military a model that increased the quality of eLearning [6], included 5 general phases and 19 detailed steps, products and resulted in products that were truly several of which call for iterative review and refine- beneficial to learners. [14] ment. [11]
According to Allen, “The ADDIE process is past its ADDIE, which is often simplified to include only the prime. It was developed long before Agile and other top-level steps of the original ISD model, is typically iterative processes that have introduced greater shown in ways that highlight the cyclic nature of the efficiencies in design and development, fostered process.
Figure 4. Successive Approximation Model (SAM) [15]
Figure 5. Instructional Systems Development Model [12]
2015 STC Technical Communication Summit Proceedings 87 Tools and Technology
All three of these instructional design models are Novices in any field have a tendency to latch onto highly iterative, and can be adapted, as needed, to any guidance and follow that guidance in a literal, implement process improvements and ensure that step-by-step manner. Only later, when they become projects are successful. more proficient, do novices adapt a more flexible approach. Experts use models… by first looking at them to understand the intent of the model and see the recommended processes, then by making adjust- ments when applying the model to their specific circumstances…” [6]
The misinterpretation and misapplication of development models can also lead to a great deal of unnecessary expense as companies invest in sys- temic changes that aren’t necessarily warranted—a subtler and more expert-level approach, in which a model is adapted based on concrete circumstances, is less expensive and more effective.
The Advantages of Using Development Models
When used correctly and expertly, models can be tremendously useful, and can lead to measurable Figure 6. Analyze, Design, Develop, Implement, and process improvements. Evaluate (ADDIE) Model [13] Process improvement is the proactive effort to iden- The Dangers of Using tify, analyze, and modify processes and standards to increase the quality, efficiency, consistency, and Development Models return on investment. Implementing processes and standards can be difficult, as many are resistant The largely artificial dichotomy between Waterfall to change and because, so often, processes and and Agile and between SAM and ISD reveals one of standards end up creating an additional burden on the dangers in relying too heavily on a static inter- employees and creating points of congestion in the pretation of any development model—a rigid misap- development process. plication of the model, based on a lack of dynamic understanding and flexibility, that leads to processes A defining characteristic of quality processes is that that are ineffective, time-consuming, demoralizing, they enable success and effectively make employees’ and result in a low-quality product. The intent of lives easier by reducing duplicate work, reducing the these process models is to create checkpoints for amount of time required to decide on minutia, and refinement and re-evaluation, in order to ensure by providing tools that make it faster and easier to both product quality, and efficicency of production. create consistent products. But these checkpoints only work if they are dynam- ically defined by the capabilities and needs of the Development models can facilitate clear communica- company, as well as the needs of the consumer. In tion and be used to demonstrate important concepts terms of process improvement, it is critical, then, to related to design, development, and the development remain flexible and to implement the model in ways cycle. that are adapted to particular risks, requirements, products, resources, and other factors. Propper use of development models can facilitate:
As stated by Hannum [6], one of the original devel- • Higher morale through unity, a shared vision, opers of the ISD model in the 1970s, “…developers clear expectations, and increased success. who are relative novices… may cling to the model • Transitions that are seamless and, therefore, and treat it as a paint-by-numbers approach. cost-efficient, because new team members
88 2015 STC Technical Communication Summit Proceedings Iterative Development Models and Process Improvement
and leaders have a clear vision of the overall is subsidiary, tangential, and often considered a process and where in the process the project necessary expense and an inconvenience. Because of is at any given time. this, it is critical that technical information designers be extremely adept at flexibly adapting to the restric- • Identifying points of congestion in the tions imposed by schedule, resources, requirements, development process; that is, points at which audience, and other factors. development is slowed or stalled. [7] • Identifying excessive back and forth; that is, In addition to the basic phases common to nearly points at which the process of communica- all development models (gathering information tion is taking an inordinate amount of time. and planning; design and development; and testing, [7] review, and refinement), I typically incorporate two additional phases: Synthesize and Prepare. • Identifying sources of defects and duplicate work; defining the phases of a process makes it easier to identify the point at which defects Synthesize are being introduced. [7] • Maintaining consistency, which is a funda- Analysis is a common early phase in development mental component of quality. [7] models, and refers to the detailed examination of the elements or the structure of something—analysis is Development models can also be used to typified by separating something into smaller, more demonstrate: manageable components. Synthesis, in contrast, refers to combining elements together to form • Quality—Because iterative development something new. The process of synthesis is critical to models are based on the premise that a quality information design, and is the phase during product will need improvement after initial which you can incorporate audience analysis, task development, the model can be used to analysis, user experience, and other concepts in demonstrate that, while the product may order to reformulate information and ensure that clearly need additional improvement, quality it is useful and high quality. The spirit of synthesis expectations are being met for a given stage is akin to what is often called design thinking, a in the process. solution-based, creative approach that emphasizes • Efficiency—Development models can be used empathy and user-centeredness, reframing all to show where a project is in the develop- possibilities, and prototyping. [16] The advantage ment cycle, and demonstrate how the pace at to adding this step to the process is that it provides which requirements are being met fits with an opportunity to innovate, and to move away from expectations (schedule). patterns that have been repeated simply to avoid • Trajectory—Development models can com- disrupting the status quo. municate to others what will happen next. “A process model answers two main questions: Prepare What should be done next? For how long should it continue?” [9] Preparation refers to the process of creating the tools, process guidelines, and standards that will ensure Iterative Model Adapted for the actual development process proceeds quickly and efficiently. Often, development begins without Technical Information Design any preparation, which inevitably leads to re-work and defects—without standards (and, therefore, Adapting iterative development models for technical without having defined what constitutes a defect), it information design can lead to significant process is impossible for developers to create quality, con- improvements. In technical information design, sistent deliverables. The products of the preparation deliverables are often developed in support of other, phase include templates, style guidelines, graphic primary products. For example, a training manual asset libraries, user interface kits, quick-reference may be developed for customers in support of a guides, and more. The advantage to adding this step software product, which is the company’s primary is tremendous: iterations (such as feedback from deliverable. This means that, quite often, the internal and external stakeholders) can be concen- development process for technical communication trated on a smaller, non-variable set that includes
2015 STC Technical Communication Summit Proceedings 89 Tools and Technology
the tools and templates, rather than the entire set of Development Models Across Industries final deliverables, and small details can be decided on, documented, communicated, and, when possible, Many managers base important strategic business created, so that developers (writers and designers) decisions on industry trends as they are presented can focus more on the decisions that require their in mass media, rather than on in-depth scholarly expertise. research; therefore, the development models listed below include those found in both scholarly (peer-re- As with all development models, this model should viewed) and non-scholarly sources. be tailored to the requirements of a specific situation, and, within each phase, iterations should take place Across industries, there are many development mod- as often as common sense allows. Iterating early and els, including: often has positive consequences in that, not only does it reduce the number of defects and the amount • Agile (Industry: Software Development) of re-work, it also generates buy-in, facilitates col- • Analyze, Design, Develop, Implement, laboration, and reinforces a sense of teamwork. In Evaluate (ADDIE) (Industry: Instructional addition, using an iterative development model for Design) technical information design allows you to develop technical information that is usable and can be • Building Information Modeling (BIM) delivered much earlier than if it is developed without (Industry: Construction) iterations. • Business Process Improvement Model (Industry: Process Improvement)
Figure 7. Iterative Model Adapted for Technical Information Design 90 2015 STC Technical Communication Summit Proceedings Iterative Development Models and Process Improvement
• Complete Management Service over the Life • Scientific Method (Industry: Sciences) of the Project (Industry: Construction) • Simplex Innovation Process (Industry: • Consensus Flowchart (Industry: Conflict Design) Resolution) • Sims and Jones’ (2003) Three-PhaseDesign • Converge Voice of the Employee (VoE) (3PD) (Industry: Instructional Design) (Industry: Process Improvement) • Social Action and Scientific Inquiry • Creative Process Model (Industry: Design) (Industry: Marketing) • Design Thinking at SAP (Industry: Software • Spiral (Industry: Software Development) Development) • Strategic Development Process (Industry: • Design Thinking Process (Industry: Design) Industrial Design) • Dick and Carey Systems Approach Model • Successive Approximation Model (SAM) (Industry: Instructional Design) (Industry: Instructional Design) • Dual Process of Reasoning (Industry: Health • Top-Down Design (Industry: Software Care) Development) • Engineering Method (Industry: Engineering) • Typical Stage-Gate Process (Industry: Construction) • Good Manufacturing Practice (GMP) (Industry: Pharmaceuticals) • Waterfall (Industry: Software Development) • IDEAL Model (Industry: Process • A Web Site Designed: Milestones, Improvement) Involvement, Importance, and Timeline (Industry: Web Design) • Instructional Systems Design (ISD) (Industry: Instructional Design) • Web-Based Instructional Design Model (Industry: Instructional Design) • Integrated Sustainable Design Thinking Process (Industry: Ecology) • Iterative Optimization Cycle (Industry: References Marketing) [1] Hamilton, Richard L. Managing Writers: A • Life Cycle Model (Industry: Project Real World Guide to Managing Technical Management) Documentation. (Fort Collins, CO: XML Press), 2009. • LX Design Process (Industry: Manufacturing) [2] Hughey, Douglas. “Comparing Traditional Systems Analysis and Design with Agile • PDCA Cycle (Industry: Quality Assurance) Methodologies.” (Copyright 2009. • PMBOK Process Model (Industry: Project Accessed 28 April 2015.) http://www.umsl. Management) edu/~hugheyd/is6840/waterfall.html. • Practice of Conversation (Industry: Land [3] GlobalTeckz. “Characteristics of Agile Management) Methodology in Software Development.” GlobalTeckz (Copyright 2015. Accessed 28 • PRINCE2 Process Model (Industry: Project April 2015.) http://blogs.globalteckz.com/ Management) characteristics-of-agile-methodology-in- • Progressive Problem-Solving with Action software-development/. Research (Industry: Social Change) [4] Wikipedia. “Waterfall Model.” Wikipedia. (Accessed 29 April 2015). http:// • Project Management (Phases) (Industry: en.wikipedia.org/wiki/Waterfall_ Project Management) modelhttp://en.wikipedia.org/wiki/ • Quality Enhancement Cycle (Industry: Waterfall_model. Quality Assurance) [5] Benington, Herbert D. “Production of Large • Scientific Method (Industry: Sciences) Computer Programs.” ICSE 87 (1987) 299-310. http://sunset.usc.edu/csse/ 2015 STC Technical Communication Summit Proceedings 91 Tools and Technology
TECHRPTS/1983/usccse83-501/usccse83- [15] Sites, Richard. “Be a SAM Superstar with ‘The 12 501s.pdfhttp:/sunset.usc.edu/csse/ Days of SAM’.” Allen Interactions (Copyright TECHRPTS/1983/usccse83-501/usccse83- 26 November 2014. Accessed 28 April 501s.pdf. 2015). http://info.alleninteractions.com/ [6] Hannum, Wallace. “Instructional Systems be-a-sam-superstar-with-the-12-days-of-sam. Development: A 30 Year Retrospective.” [16] Platner, Hasso. An Introduction to Design Educational Technology 45:4 (2005): 5-21. Thinking: Process Guide. (Stanford, CA: http://dose.wallacehannum.com/ISD%20 Institute of Design at Stanford). Accessed Retrospective.pdf. 28 April 2015). https://dschool.stanford. [7] Berg, Rob. “Why Process Modeling?” Journal of edu/sandbox/groups/designresources/ Insurance Operations. (Copyright 13 June wiki/36873/attachments/74b3d/ 2011. Accessed 28 April 2015.) http://www. ModeGuideBOOTCAMP2010L.pdf. jiops.com/06/2011/why-process-modeling/. [8] English, Stuart. “Design thinking–Value Author Contact Information innovation–Deductive reason and the Tina M. Kister, PMP designers choice.” Design Research Society Senior Technical Information Designer Conference, Lisbon (2006) 1-4. http:// University of Florida (Graduate Student) www.iade.pt/drs2006/wonderground/ 2338 River Park Circle Apt. 1836 proceedings/fullpapers/drs2006_0180.pdf. Orlando FL 32817 [9] Boehm, Barry, and Wilfred J. Hansen. “Spiral +1.435.260.1565 Development: Experience, Principles, and Refinements.” Special Report CMU/SEI- 2000-SR-008. Pittsburgh, PA: Carnegie Author Biography Mellon Software Engineering Institute), 2000. Tina M. Kister is a technical writer and designer whose passion is combining quality content with [10] Allen, Michael. Leaving ADDIE for SAM: great design. With experience in a wide range of Faster, Better Learning Product fields, including natural sciences, instructional Development. (Alexandria, VA: American design (military), health care, engineering, construc- Society for Training and Development), 2012. tion, fine art, advertising, and more, she specializes [11] Branson, Rober K., Gail T. Rayner, J. Lamarr in a cross-discipline approach that embraces best Cox, John P. Furman, F. J. King, and Wallace practices across industries, and seeks to take quality H. Hannum. Interservice Procedures technical information and make it compelling and for Instructional Systems Development: pleasing. Phase II—Design. (Tallahassee, FL: Florida State University Center for Educational She is currently working on a Master’s degree in Technology), 1975. Mass Communications with a focus on Web Design [12] Clark, Donald. “ADDIE Timeline.” Big Dog and Online Communications at the University of & Little Dog’s Performance Juxtapositon Florida. (Copyright 13 July 1995. Accessed 28 April 2015). http://www.nwlink.com/~donclark/ history_isd/addie.html. [13] ADDIE Solutions, LLC. “The ADDIE Model.” ADDIE Solutions, LLC (Accessed 28 April 2015). http://www.addiesolutions.com/ addie.htm. [14] Allen Interactions. “Leaving ADDIE for SAM: eLearnChat Interview with Michael Allen.” Allen Interactions (Accessed 28 April 2015). http://info.alleninteractions.com/ bid/91770/Leaving-ADDIE-for-SAM- eLearnChat-Interview-with-Michael-Allen.
92 2015 STC Technical Communication Summit Proceedings 2015 STC Technical Communication Summit 21–24 June 2015 • Columbus, Ohio © 2015 Society for Technical Communication
EPUB: ONE FORMAT FOR ALL DELIVERABLES Scott Prentice
EPUB 3, built on HTML 5 and CSS 3, can include interactivity, videos, audio clips, and can read aloud to the user. It works with vertical, left to right, and right to left content. The content can flow from page to page (a traditional ebook), it can be topic-based and scroll vertically (like a typical Help system), or it can be formatted in a fixed layout (like a PDF). All of this in one neat little package that can be read on most devices and platforms. The tools aren’t there yet, but in time EPUB could be the “all” format for techcomm. This presentation discusses the pros and cons of the various options and shows working proto- types. If you’re looking for a single file deliverable that does it all, EPUB may be for you.
Let’s Start at Page One which includes a fixed layout (FXL) format as well as support for Indexes. The EPUB 3.1 draft is currently hat is an EPUB? It’s is an ebook file format that available for review, which adds a number of new Wcan be read on almost every device and plat- features around scripting, media, and accessibility. form: desktop, laptop, tablet, phone (and perhaps someday your watch or refrigerator!). It requires the installation of a reader application (ereader) EPUB 3 is the Key or the use of a dedicated device that has a reader application built-in. Inside an EPUB is a collection of The thing that changed EPUBs from being “just an XHTML, XML, CSS, and media files wrapped up in a online book” to something much more was the intro- “zip” archive (conceptually like a CHM file that you’re duction of EPUB 3. EPUB 3 is based on HTML 5 and probably familiar with). It’s a nice neat little package CSS 3, which opens up a huge array of formatting, of content and formatting that can be easily provided layout, and interactivity options that were previously to users who can add your ebooks to their online not available. libraries for reading whenever needed. Prior to EPUB 3, scripting (use of JavaScript) was An EPUB is a self-contained deliverable that defines explicitly discouraged by the specification, and the content, navigation, and formatting of the ebook. was thus not supported well in ereaders. EPUB 3 Because of this it’s perfect for documentation that reverses that by stating that scripting is supported as needs to be available for off-line reading. But an defined in the HTML 5 and SVG specifications. It’s EPUB can be oh so much more than “just an online important to note that while scripting is now “sup- book,” and that’s what we’ll discuss here. ported,” it is optional for “Reading Systems” (eread- ers) to implement. However, because of the focus on The EPUB specification is maintained by the IDPF interactivity, most ereaders will support a certain (International Digital Publishing Forum). EPUB level of scripting. became an official standard in 2007, superseding the older Open eBook standard (from 1999). Since then, From a security standpoint, each “Content EPUB 2.0.1 was approved in 2010, and the latest Document” (an XHTML file in the EPUB) is treated specification, EPUB 3, was approved in October as a separate “domain.” This means that the rules 2011. As of June 2014 EPUB 3.0.1 was approved of cross domain scripting apply as they would on 93 Tools and Technology
a website, limiting what you can access from any self, as you might when developing a website. The given document. (It appears that this may change following features can be expected in most ereaders: with EPUB 3.1 as they are considering enabling cli- ent-side cross-origin requests as defined in the W3C • Table of contents. Based on the TOC CORS specification.) information you provide in the EPUB • Bookmarks. Most ereaders will provide The use of scripting includes the ability to leverage some way for the user to place bookmarks many of the JavaScript libraries that are available for easy access at a later date. for performing special purpose tasks. One library of particular interest is jQuery. This can be very useful • Reader notes. Many ereaders will provide for enabling interactivity with document content as the option for the user to make notes and well as dynamically modifying the content based on highlight passages or words in the content. the ereader screen size or orientation. There are also • UI customization. Most ereaders will libraries that make it easy to generate charts and allow user-defined setting of fonts, font size, graphs from raw data, as well as manipulating SVG and colors (background and font) graphics. The options are virtually limitless. Additional navigation features may be available and Through the inclusion of HTML 5, EPUB 3 supports implemented in various ways: SVG and MathML, as well as embedded audio and video. An EPUB can include Media Overlay • Search. Most ereaders have something Documents which make use of the SMIL speci- called “Search”, but it may in fact be a page- fication (Synchronized Multimedia Integration by-page “Find” rather than a proper full text Language) to allow the synchronization of audio with search. Oddly enough, most mobile ereaders the highlighting of document content. This provides will have a better search implementation for a “read aloud” EPUB that may be useful in vari- than desktop ereaders. ous situations, specifically for educational books and • Index. Because this is in the EPUB 3.0.1 to assist individuals with print disabilities. specification, you should start seeing eread- ers that support the new Index functionality. CSS 3 provides extensive formatting and language However, as of this writing, there are none support. This means that ereaders should support that I’m aware of. bi-directional text (left to right and right to left), as well as vertically oriented text. It should also support Because these features are all implemented slightly special properties of vertically-oriented text. Media differently, you should not rely on one particular queries are also supported, which greatly simplifies implementation. You should test as many ereaders the implementation of a “responsive” EPUB. as you can, and provide the results to your end users. When you offer an EPUB as a documentation deliv- One of the new features offered in the EPUB 3.0.1 erable, you should list a handful of recommended specification is the Fixed Layout format (known ereaders, but design the EPUB to be functional on as as FXL). This was intended to be used to create many ereaders as possible. specialty books that required a fixed, non-paged layout, like comic books, children’s books, or other graphic-intensive books where a precise page layout Layout Implementations is required. Given the functionality and layout options now avail- This is just a small sampling of the new features able with the EPUB 3.0.1 specification, the following available through EPUB 3. Because of this, I like to fundamental layouts can be achieved: say that an EPUB is a “website in a box”! • Paged model. This is the “traditional” ebook layout, where the content flows from Ereader Features page to page and fills the available screen space. This is a good choice for many types of EPUB reader applications and devices will typically content, and is more likely to render properly provide a standard set of navigation features, which on the widest array of ereaders. means that you don’t have to implement them your-
94 2015 STC Technical Communication Summit Proceedings EPUB: One Format for All Deliverables
• Fixed layout (EPUB-PDF). This new lay- • Learning and training material. Could out option added with EPUB 3.0.1 can pro- benefit from the vertically scrolling top- vide an EPUB that looks and functions just ic-based model enhanced with scripting and like a PDF. While there are no tools that will forms for interactivity. Would also make use create this type of EPUB, it can be created of embedded audio and video. “by hand” or possibly through scripting and • Online help. Most likely suited for the automation. With a little pressure, we may vertically scrolling topic-based model. Would be able to convince tool vendors to support benefit from the ability to open an EPUB on this type of output. a specific topic to provide context sensitivity. You might logically ask, “if this looks and functions just like a PDF, why not just use • Print-ready documents. Ideally suited for a PDF?” The only viable reason I can think a fixed layout EPUB. of at this time, is that while it can look and function just like a PDF, it can do more than you can do with a PDF. It can be interactive Issues and Limitations and you can make use of scripting. In reality, the use case for this is a stretch, but it’s good As with all good things there are always limitations. to be aware that this type of thing is possible. Currently, none of the publishing tools support Keep it in the back of your mind and you the more interesting EPUB 3 features. This means never know when it’ll find a sensible use. that you’ll probably need to hand-code for anything beyond simple formatting in a traditionally paged • Vertically scrolling (EPUB Help). This EPUB. Hopefully this will change as tool vendors see option makes use of scripting and CSS to the benefits of offering more interesting and useful force onto one page all of the content for a features. document that would normally span multi- ple pages. If the “overflow” property is set to The other problem is that the reader applications “auto,” the page will scroll vertically, just like and devices all support varying levels of the EPUB it does in a traditional compiled Help system 3 specification. This will limit what you can actually like HTML Help or Java Help. By doing this provide to your end users, and will restrict the read- you’ve basically got a single-file deliverable ers that they can use. Help system that will run on all platforms and devices. Until these issues are resolved, especially with regard With the apparent demise of HTML Help, to the tools, these ideas will not provide truly viable many people are left looking for the next publishing options that are likely to be adopted on a way to deliver online Help. Java Help is an large scale. But they are worth watching and experi- option, but it has problems of its own. The menting so that you’re ready to move when it makes only other option is some type of “web help” sense to do so. that runs in a browser. This can be locally installed or server-based, but it’s a collection of loose HTML files. This may work for some, Useful Internet Resources but for others it doesn’t really fit their needs. IDPF – EPUB 3.0.1 Specification. –http://idpf.org/ epub/301 One Format for All Deliverables? IDPF – EPUB 3 Specification. – http://idpf.org/ epub/30 With EPUB 3, this format can (theoretically) provide support for all of the common techcomm IDPF – EPUB 2.0.1 Specification. –http://idpf.org/ deliverables. epub/201 Castro, Liz. – http://www.pigsgourdsandwikis.com/ • User guides. A good choice for both the traditional paged layout as well as the verti- eBook Architects. – http://ebookarchitects.com/ cally scrolling topic-based model. resources/ ePrdctn on Twitter. – https://twitter.com/#!/ • References. Likely best suited for the verti- search?q=%23eprdctn cally scrolling topic-based model.
2015 STC Technical Communication Summit Proceedings 95 Tools and Technology
EPUB Resources. – http://epubtest.com/resources. php
Author Contact Information Scott Prentice Founder and President Leximation, Inc. 122 H Street, San Rafael, CA 94901 +1.415 485 1892 www.leximation.com
Author Biography
Scott Prentice is the founder and president of Leximation, Inc., and has been in the technical publication field since 1991. His work focuses on custom online Help development, XML conversions, FrameMaker (plugin and structure application) development, as well as custom web application development. He is very involved with DITA and cre- ated the DITA-FMx plugin for FrameMaker. He is an invited expert on the IDPF EPUB 3 Indexes working group.
96 2015 STC Technical Communication Summit Proceedings EPUB: One Format for All Deliverables
2015 STC Technical Communication Summit Proceedings 97 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 2015 STC Technical Communication Summit 21–24 June 2015 • Columbus, Ohio © 2015 Society for Technical Communication
EFFECTS OF ELECTRONIC MEDIA ON TECHNICAL/SCIENTIFIC COMMUNICATION: A LOOK AT THE BP/HORIZON DEEPWATER OIL RIG EXPLOSION Carolyn Boiarsky, Ph.D., Associate Fellow
Electronic media have exacerbated the problems associated with communicating effec- tively, especially when the topic is complex. Recent research on where and when messages are read and the number of messages read and sent in a single day are mind-boggling. This paper discusses these findings as they affect communication in technical/scientific fields. A rhetorical analysis of the emails sent between engineers and managers involved in the BP/Horizon Oil Rig Explosion indicates three major problems inherent in commu- nicating electronically and provides suggestions for overcoming these problems.
Introduction This paper discusses the problems in communicating technical and scientific information. Messages are lectronic media as a means of disseminating ‘information-poor,’ writer- rather than reader-ori- Einformation have become ubiquitous. Almost ented, and a-synchronous. The paper looks specifi- all technical and scientific communication today is cally at these problems as they relate to the commu- conducted electronically (Dabbish, Kraut, Fussell, et nication that occurred between the engineers and al 2005; Louhiala-Salimen 1999). Recent research managers involved in the BP/Horizon Deepwater oil on where and when messages are read and the num- rig explosion. ber of messages read and sent in a single day are mind-boggling. For those between the ages of 18-39, the smart phone has become the primary device for Information Poor reading emails (Marketing Charts Staff 2014). Users check their smart phones for email approximately Emails and text messages are often ‘informa- 150 times a day (Mujamdar 2013). The typical cor- tion-poor’ (Ekroth 2014). Writers fail to include porate email user receives about 105 emails per day background information and details, increasing the (Radicati Group 2011). potential for misunderstanding as well as requiring both the writer and the responder to expend an With the demand for the Apple watch outpacing increased amount of time writing additional threads production (New York Times 2015), it is evident that in a chain in order to obtain all of the information emails and texts are migrating to the new medium. needed to make a decision or to do something. While watches have not been around long enough to (Conversation threads related to the same subject collect data, it is estimated that these devices will at create a chain of emails or text messages with partic- least parallel Smart phones as the device of choice ipants responding sequentially to each other). for reading messages.
99 Training and Research
In Figure 1, which relates to the preparation on the tronic messaging with social media. Twitter with its BP/Horizon oil rig to cap the well, Dobbs apparently 140 character maximum, Facebook, Linked In, and has not received any background information that Pinterest are all minimally worded. would have provided her with an understanding for the decision to use a 7”liner. Morel provides her with Writers also often omit necessary information a basic explanation but there is apparently more because they perceive their readers as being similar that she might want to know as he adds “If you want to their readers on social media sites. Sites, such more details, let me know.” Thus, she may need to as Facebook and Linked In, are composed of closed continue the chain. Furthermore, Morel does not groups of people in which certain knowledge or provide a response to her question about an SOR so interests are held in common. A group of individ- she may need to repeat the question in an additional uals who share similar experiences and knowledge, thread. composes a “high context” culture. The term was introduced by the anthropologist Edward Hall (1976) Writers often fail to provide sufficient information in his book Beyond Culture. Communication within because of the pressure to provide an immediate these sites involves “high context” messages in which response to a request (Morel responds to Dobbs background information and details are often omit- request within 20 minutes). They also omit nec- ted because it is assumed (correctly) that readers are essary information because of their tendency to knowledgeable in the topics under discussion. conflate social media communication with that of business. A problem in communication occurs when writers mistakenly believe that their audiences--employees, managers, clients and subcontractors in large corpo- Pressure to Respond Instantly rations and organizations—are similar to their read- ers on Linked In and Facebook, high context groups Both managers and employees expect an immediate that have similar interests and vocations. They are response to their messages, creating an electronic not. In technical/scientific business environments, communication overload (Jackson 2012; Barley readers may be located in different geographic 2011) which for want of a better name I shall call locations, have different specialties and be assigned ECSS (Electronic Communication Stress Syndrome). to different divisions. They often need background Many employees are expected to be on call 24/7, information and elaborated details to understand a regardless of whether they are in an office, having message. When writers fail to realize that they are dinner with their family or at an off-site confer- writing in a low rather than a high context environ- ence. This has resulted in messages being read and ment, they may omit information their readers need responded to quickly, with as few words as possible to complete a task or make a decision. and without much thought (Skovhold 2009). Often writers are typing at the same time that they are Recognizing the pressure to respond and the time it walking along an office corridor, eating lunch, or takes away from a task, Couch, working on the BP/ cooking dinner. Horizon oil rig, indicates in the email in Figure 2 that the reader should not respond until he could fill the Apple’s ads proclaim the device’s ability not only request. Pat responds about 1 ½ hours later but Tom to “tap” the wearer immediately when a message doesn’t check on the message until 3 hours later and, arrives, but to provide the wearer with the message when he does, he makes further requests. “front and center” on its face. It is a fairly good bet that, as a result of the device’s ability to gain the wearer’s immediate attention, the expected response Writer-Based Orientation time and the length of the message will become even shorter than they already are. The conflation of social media correspondence with business communication causes other problems. By (con)fusing the style of social media with that of Conflating Social Media Conventions business/technical correspondence, writers create writer- rather than reader-based messages. The With Business Correspondence term writer-based prose was coined by Linda Flower (1999) to define texts in which the writer writes for Writers often fail to include background information him/herself, ignoring the reader’s needs and failing and detail because they mistakenly conflate elec-
100 2015 STC Technical Communication Summit Proceedings Effects of Electronic Media on Technical/Scientific Communication
Boiarsc(((Effects(of(Electronic(media((((
( From: Dobbs, Sarah Sent: Tuesday, March 30,2010 10:33 AM To: Morel, Brian P; Hafle, Mark E( Cc: PTNEDA, FRANCISCO( Subject: Pip Tags and Casing(
Guys(G( We(would(like(pip(tags(near(the(casing(hanger,(just(below(the(production( liner(top,(just(above(the(sand,(and(one(near(TD.( Also,(what(swayed(the(decision(to(7"(liner?(((Was(it(availability(or(cementing(concerns?( And,(for(historical(knowledge,(in(August(it(looks(like(y'all(discussed((with(Hu)( the(option(of(10G3/4"(casing(to(3000'(below(the(mudline(to(accommodate(a( larger(1(5K(SCSSV.(((It(was(our(understanding(that(the(casing(was( unavailable,(so(that(option(was(eliminated.(Is(that(correct?( By(the(way,(do(y'all(know(if(there(is(an(SOR(floating(around(for(this(well.( ( Sarah(Elisabeth(Dobbs(( BP(Gulf(of(Mexico(Deepwater(( Completions(Engineer( GGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGG( From: Morel, Brian P( Sent: Tuesday, March 30,2010 10:54 AM( To: Dobbs. Sarah; Hafle, Murk E( Cc: PINEDA, FRANCISCO( Subject: RE. Pip Tags and Casing( 7" is so we can run a long string instead of a tieback and still cement If we had run 7-5/8" we would not have been able to cement as a long string with the amount of casing available, and would have had to double the source -3000' extra to bring the 7-5/8" above the 11-7/8" hanger a few hundred feet. We did not have this pipe in stock or easily available, and were able to get T from Ncxcn.(
Not running the tieback, saves a good deal of time/money as well as reduces complexity due to the conventional casing hanger or having to run a second packer and PBR assembly for the Versaflex hanger. If you want more details let me know.(
We will take care of getting the pip tags. Do you want the casing hanger one moved to the top of the cross-over instead? Thanks Brian( GGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGG( ( From:(Dobbs,(Sarah( Sent:(Wed(Mar(31(21:15:192010( To:(Morel,(Brian(P( Subject:(RE:(Pip(Tags(and(Casing( Importance:(Normal( ( Yes, that is great. Thanks. ( Sarah(Elisabeth(Dobbs( BP(Gulf(of(Mexico(Deepwater(( Completions(Engineer(
Figure 1. Request and response in an email thread. Figure(1.(Request(and(response(in(an(email(thread.(
2015 STC Technical Communication Summit Proceedings 101
(((((7((((((7/13/2015(5:25(PM(((((( ( Training and Research
Boiarsc(((Effects(of(Electronic(media((((
( From: Couch, Thomas E Sent: Wednesday. March 24,2010 9:39 AM To: Smith Ridley; Alfonso delas Cuevas; Crane, Allison; | '[email protected]; "[email protected] Subject: BP is looking For 7" Liner
STA, BP is looking for approx 5,500 feet of 7.00", 32#, Q-125, Hyd. 513 or 523 Liner. Will look at other connections and possibly PI 10 material PLEASE DO NOT RESPOND UNLESS YOU HAVE SOMETHING TO OFFER.
Regards and Thanks, Tom Couch BP Exploration & Production Co. PSCM, Materials Management, GoM SPL
From: Rincon, Pat (Dallas) Sent: Wednesday, March 24,2010 10:52 AM To: Couch, Thomas E Subject: RE: BP is looking for 7" Liner
Tom,
Nexen has 6,000' - T32# Q-125 HC Hydril 513
Condition A - recently inspected
What's your need date?
Subject to management approval - will pursue if you are interested.
Pat C. Rincon
Sr Buyer, Supply Mgrat Nona Petroleum US A. Ine
From: Couch, Thomas E Sent: Wednesday. March 24.2010 12:26 PM To: Rincon, Pat (Dallas) Cc: Crane, Allison Subject: RE: BP is looking for 7" Liner Pat, This looks really good. Still don't have exactly what they're going to do in this well yet
If it's not too much trouble do you have the following that you could send? 1.( The location of the pipe 2.( The recent inspection report(s)- we may not need to reinspect. 3.( The Mill or MTR(s) even better. Just as soon as we know the outcome of the requirement, we'll let you know.
Regards and Thanks, Tom Couch BP Exploration & Production Co. PSCM, Materials Management, GoM SPU
Figure 2. Request and response in an email chain Figure(2.(Request(and(response(in(an(email(chain(
102 (((((8((((((7/13/2015(5:25(PM(((((( 2015 STC Technical Communication Summit Proceedings ( ! !
Effects of Electronic Media on Technical/Scientific Communication
Boiarsc(((Effects(of(Electronic(media((((
( Hi(David,( ( I(talked(to(Carlisle(a(bit(ago(and(he(let(me(know(you(guys(at(MOD(were(getting(into(the(loop(on(the( tile(damage(issue.(I'm(writing(this(email(not(really(in(an(official(capacity(but(since(we've(worked( together(so(many(times(I(feel(like(I(can(say(pretty(much(anything(to(you.(And(before(I(begin(I(would( offer(that(I(am(admittedly(erring(way(on(the(side(of(absolute(worstGcase(scenarios(and(I(don't(really( believe(things(are(as(bad(as(I'm(getting(ready(to(make(them(out(But(I(certainly(believe(that(to(not(be( ready(for(a(gutGwrenching(decision(after(seeing(instrumentation(in(the(wheel(well(not(be(there(after( entry(is(irresponsible.(One(of(my(personal(theories(is(that(you(should(seriously(consider(the( possibility(of(the(gear(not(deploying(at(all(if(there(is(a(substantial(breach(of(the(wheel(well((color( mine).(The(reason(might(be(that(as(the(temps(increase,(the(wheel((aluminum)(will(lose(material( properties(as(it(heats(up(and(the(tire(pressure(will(increase.(At(some(point(the(wheel(could(fail(and( send(debris(everywhere.(While(it(is(true(there(are(thermal(fuses(in(the(wheel,(if(the(rate(of(heating(is( high(enough,(since(the(tire(is(such(a(good(insulator,(the(wheel(may(degrade(in(strength(enough(to( let(go(far(below(the(1100(psi(or(so(that(the(tire(normally(bursts(at.(It(seems(to(me(that(with(that( much(carnage(in(the(wheel(well,(something(could(get(screwed(up(enough(to(prevent(deployment( and(then(you(are(in(a(world(of(hurt.(The(following(are(scenarios(that(might(be(possible...and(since( there(are(so(many(of(them,(these(are(offered(just(to(make(sure(that(some(things(don’t(slip(thru(the( cracks...!(suspect(many(or(all(of(these(have(been(gone(over(by(you(guys(already:(
1(People(talk(about(landing(with(two(flat(tires...!(did(too(until(this(came(up.(If(both(tires(blew(up(in( the(wheel(well((not(talking(thermal(fuse(and(venting(but(explosive(decomp(due(to(tire(and/or(wheel( failure)(the(overpressure(in(the(wheel(well(will(be(in(the(40(+(psi(range.(The(resulting(loads(on(the( gear(door((a(quarter(million(IDS)(would(almost(certainly(blow(the(door(off(the(hinges(or(at(least(send( it(out(into(the(slip(stream.(..catastrophic(((Even(if(you(could(survive(the(heating,(would(the(gear(now( deploy?(And/or(also,(could(you(even(reach(the(runway(with(this(kind(of(drag?( 2..(The(explosive(bungles...what(might(be(the(possibility(of(these(firing(due(to(excessive( heating?( If(they(fired,(would(they(send(the(gear(door(and/or(the(gear(into(the(slipstream?( 3.(What(might(excessive(heating(do(to(all(kinds(of(other(hardware(in(the(wheel(well...the( hydraulic(fluid,(uplocks,(etc?(Are(there(vulnerable(hardware(items(that(might(prevent( deployment?(( 4.(If(the(gear(didn't(deploy((and(you(would(have(to(consider(this(before(making(the( commitment(to(gear(deploy(on(final)(what(would(happen(controlGwise(if(the(other(gear(is(down( and(one(is(up?( (I(think(Howard(Law(and(his(community(will(tell(you(you're(finished)( 5.(Do(you(belly(land?(Without(any(other(planning(you(will(have(already(committed(to(KSC.( And….( Admittedly(this(is(over(the(top(in(many(ways,(but(this(is(a(pretty(bad(time(to(get(surprised(and(have(to( make(decisions(in(the(last(20(minutes.(You(can(count(on(us(to(provide(any(support(you(think(you(need.( Best(Regards,( Bob( (
Figure(3.(A(rambling(email(related(to(the(potential(effects(of(the(floating(tile(on(the(Columbia(Shuttle.(
( (
Figure 3. A rambling email related to the potential effects of the floating tile on the Columbia Shuttle._
2015(((((9 STC((((((7/13/2015(5:25(PM Technical Communication(((((( Summit Proceedings 103 ( Training and Research
Boiarsc(((Effects(of(Electronic(media((((
( David, over the past four days there has [sic] been so many last minute changes to the operation that the WSL 's [well site leaders] have finally come to their wits end The quote is —flying by the seat oj our pants. Moreover, we have made a special boat or helicopter run every day. Everybody wants to do the right thing, but. this huge level of paranoia from engineering leadership is driving chaos. This operation is not Thunderhorse [one of the world's largest rigs ever built. The rig was damaged by Hurricane Dennis.] Brian has called me numerous times to make sense of all the insanity. Last night's emergency evolved around 30 bbls [barrels] of cement spacer behind the topping and how it would affect any bond logging (1 do not agree with putting the spacer above the plug to begin with). This morning Brian called me and asked my advice about exploring other opportunities both inside and outside of the company. ______
John, I've got to go to dance practice in a few minutes- Let's talk this afternoon, for now, and until this well is over, we have to try to remain positive and remember what you said below - everybody wants to do the right thing. The WSLs will take their eve from you. If you tell them to hang in there and we appreciate them working through this with its (12 hours a day for 14 days) - they will. If should be obvious to all that we could not plan ahead for the well conditions we 're seeing, so WE have to accept some level of last minute changes.
We 've both [been] in Brian's position before. The same goes for him. We need to remind him that this is a great learning opportunity, it will be over soon, and that the same issues - or worse - exist anywhere else. I don't think anything has changed with respect to engineering and operations.
Mark and Brian write the program based on discussion "direction from you and our best engineering practices. If we had more time to plan this casing job, I think all this would have been worked out before it got to the rig. If you don't agree with something engineering related, and you and Gregg can'i come to an agreement, Jon or me gets involved. If IT'S purely operational, it's your call.
I'll be back soon and we can talk, We're dancing to the Village People! (
(
Figure(4.(An(email(thread(between(an(engineer(on(the(BP/Horizon(oil(rig(and(a(manager(on(land.(
Figure 4. An email thread between an engineer on the BP/Horizon oil rig and a manager on land.
104 2015 STC Technical Communication Summit Proceedings (((((10((((((7/13/2015(5:25(PM(((((( ( Effects of Electronic Media on Technical/Scientific Communication to account for the reader’s prior knowledge and A-Synchronous Communication reading style and process. This orientation may result in the interjection of the “I” aspect of social Because electronic correspondence tends to be brief media into a technical/scientific message. The writer and often omits necessary background information may ramble, include irrelevant and personal infor- and details, it is a poor medium for communicating mation as well as fail to provide for readers’ reading complex information or providing a forum for patterns. conflicting ideas. However, it is used for just these purposes. Rather than a face-to-face meeting or a Tendency to ramble. The tendency to ramble not telephone discussion, people prefer to use electronic only increases the wordage in a message, but may media, believing mistakenly that emails and texts delay the presentation of the main point, creating a provide the same kind of two-way communication text that may cause readers to stop reading which that a telephone provides. But the perception that is probably what occurred when the NASA team electronic communication is two-way and that con- received the letter in Figure 3. The letter was written versations occur simultaneously and in real time is to men who were working 24/7 to try to figure out false. In most cases, they do not. They are a-synchro- the location of the damage and the size of the dam- nous (Ashley 2003). age caused to the Columbia Shuttle when a piece of foam came off on liftoff and hit the spacecraft. The During a telephone conversation, a person can ques- letter contained the best guess of all the information tion an aspect of a description, ask for the definition coming in but it was hidden in the middle of the of a term or request a fuller explanation of a topic very long introductory paragraph (highlighted by and receive an immediate response, even if it is “I me). The Commissioners charged with investigating don’t know or “I’ll get back to you.” However, during the accident concluded that those to whom it was an email or text conversation, the communication sent had probably never read far enough into the can be suspended before a response is made. Of message to find his conclusion (Columbia Accident the approximately half of all messages that people Investigation Board 2003). read, only about one third of these ever receive a response (Skovholt 2009). Yet writers not only want Inclusion of Personal Information. The (con) a response but want it immediately. This is seldom fusion of social media genres with technical/ sci- the case. The average time for a response is approxi- entific ones often leads writers to include personal mately 28 hours (Dabbish 2005). information that is not related to the focus of a message, resulting in a TMI response (Too Much The gaps in time between messages in an email Information). The email thread in Figure 4, which chain have numerous causes. Participants often occurred just before the BP/Horizon oil rig blowout, leave a chain before it is concluded because they is a prime example of this error. It was written by an have turned to other work. Whether or not a person engineer on the rig to a manager on land. In light of responds to a message immediately is usually deter- the results of the problems discussed in the email it mined by a person’s perceptions of the importance of is spine chilling. a message. Other criteria include the amount of time required for writing a response. Messages requiring Failure to provide for readers’ reading pat- more than a quick response are often put aside to be terns. Previous research has indicated that people worked on later (Stack 2009). read hard copy in a “T” pattern, reading the first paragraph and them skimming down the middle of Although reading and responding to a message the following paragraphs. New research indicates requesting attendance at a meeting can be done in that people reading emails and texts follow an “F” this fashion, reading and responding to a message pattern (Nielsen 2006), reading the first sentence, that concerns a critical engineering decision, such as skimming the remainder of the paragraph, reading the one in Figure 4, often cannot be. Because of the the beginning of the second paragraph and then ease of sending electronic messages, other forms of skimming down the left margin of the remainder of media are rejected. Yet, if issues are complex or open the document. If important information is included to misunderstanding, multiple forms of communi- in the middle, it is usually missed. cation, including the telephone, letters/memoranda, fax and person-to-person meetings, may need to be used. Both the telephone and person-to-person meetings provide real time, one-on-one opportuni-
2015 STC Technical Communication Summit Proceedings 105 Training and Research
ties to discuss a topic or clarify a misunderstanding References during a single time slot, not over a period of time. Ashley, J. (2003). Synchronous and A-Synchronous Laura Stack, President of an international con- Communication Tools. Retrieved sulting company in Denver, Colorado, claims that May 2, 2015, from: http://www. “Communication becomes richer as you add human asaecenter.org/Resources/articledetail. elements like voice, tone, facial expression and cfm?itemnumber=13572. physical expression.” She has developed a flow chart Barley, S. R, D. E. Myerson, and S. Grodal. (2011). ranging from person to person communication for Email as a Source and Symbol of Stress. ambiguous, long, or difficult messages to letters and Retrieved from http://web.stanford.edu/ reports for clear, simple messages. She places email group/wto/cgi-bin/uploads/2011%20 in the middle of the range (Stack 2009). Email%20as%20a%20Source%20and%20 Symbol%20of%20Stress.pdf. Columbia Accident Investigation Board. (2003). Conclusions and Recommendations Report vol 1. Retrieved May 2, 2015, from http://govinfo.library.unt.edu/caib/news/ To avoid some of the problems associated with report/pdf/vol1/full/caib_report_volume1. electronic media, writers should keep the following pdf. recommendations in mind: Dabbish, L. A., R. E. Kraut, S. Fussell, and S. Kiesler. 1. Place the most important information at the (2005). Understanding Email use: Predicting beginning of an email. Action on a Message. Retrieved May 2, 2015. http://www.cs.cmu.edu/~kiesler/ 2. Remember the reader’s ‘F’ reading pattern. publications/2005pdfs/2005-Dabbish-CHI. 3. Include all necessary information in a sin- pdf. 2005. gle thread. Don’t make the reader have to Ekroth, L. (2014). Have Email Conversation request more information. Problems? Retrieved from http://donmorris.com/article/ 4. Consider readers’ prior knowledge, wants have-email-conversation-problems. and needs, and provide readers with the necessary background information and Flower, L. (1999). Writer-based prose: A cognitive details they need to make a decision or do basis for problems in writing, College something. English, vol. 41, no. 1, pp.19–37. 5. If the message requires you to spend time Hall, E. (1876). Beyond Culture. New York: Anchor on a response, notify readers that you have Books, 1976. received their message and will get back to Jackson, T. (2011) Email Stress. Retrieved from them as soon as possible. This relieves you http://www.profjackson.com/email_stress. from some of the pressure to respond to html 2012. the writer, it prevents you from giving the Louhiala-Salminen, L. (1999) From Business writer only partial information in an effort Correspondence to Message Exchange: What to respond quickly, and it relieves the writ- is there left? in C, Nickerson and M. Hewings er’s anxiety, wondering if you received the (Eds) Business English: Research into message. Practice. New York: Longman. pp 100-114. 6. Follow the conventions for business/techni- Marketing Charts Staff. When Smartphone Users cal correspondence. Check Email During the Day. Retrieved 7. Refrain from including personal or irrelevant from www.marketingcharts.com/wp/online/ information. when-smartphone-users-email-during-the- day/html. March 2014. 8. Consider communicating by telephone or Mujumdar, A. (2013). Smartphone users check in-person when issues are complex. their phones an average of 150 times a day. Retrieved from http://tech.firstpost.com/ news-analysis/smartphone-users-check- their-phones-an-average-of-150-times-a- day-86984.html.
106 2015 STC Technical Communication Summit Proceedings Effects of Electronic Media on Technical/Scientific Communication
New York Times. (2015). Apple CEO Says It’s Engineering Education Conference in Sheffield, Hard to Guage Smartwatch Demand. England. Retrieved from http://www.nytimes.com/ reuters/2015/04/27/business/27reuters- apple-results-watch.html . Nielsen, J. (2006). F-shaped pattern for reading web content. Retrieved from http://www. nngroup.com/articles/f-shaped-pattern- reading-web-content/. Radicati Group, (2011). Email statistics report, 2011- 2015. Retrieved from http://www.radicati. com/wp/wp-content/uploads/2011/05/ Email-Statistics-Report-2011-2015- Executive-Summary.pdf.htm1. Skovholt, K. (2009). Email Literacy in the Workplace. Dissertation. Oslo, Norway: University of Oslo . Stack, Laura. (2009). Choose the most productive communication channel for your message. Retrieved May 4, from http:// theproductivitypro.com/blog/2009/03/ the-productivity-minute-8-channels-of- communication-and-unproductive-email/.
Contact Information Carolyn Boiarsky Purdue University Calumet CLO 221 Hammond, IN 46324 +1.219.937.4736
Author Biography
Carolyn Boiarsky is a Professor in the Department of English at Purdue University Calumet, Indiana. She has authored two books related to communicating in engineering and the technical sciences--Tech- nical Communication: Contexts, Audiences, and Communities and Writings from the Workplace: Documents, Models and Cases, published by Allyn and Bacon. She is presently writing a book (Mis) Commuication in the Engineering and Environmental Sciences for Colorado University Press which will be published both digitally and in hard copy winter 2015. She has received the Society of Technical Communication’s Frank R. Smith Article of the Year Award and has made numerous presentations at the annual conferences of the Society for Technical Communication and the IEEE/Professional Communication Society. She has also presented internationally in Limerick, Ireland and Milan, Italy; and was invited to present at the
2015 STC Technical Communication Summit Proceedings 107 Training and Research
108 2015 STC Technical Communication Summit Proceedings 2015 STC Technical Communication Summit 21–24 June 2015 • Columbus, Ohio © 2015 Society for Technical Communication
MOVING INTO INSTRUCTIONAL DESIGN Stephen Van Esch
Technical communication is an ever-expanding field. It is not unusual for a writer to be called upon to create training materials in addition to their regular duties of creating online help, manuals, and other documentation deliverables. However, technical docu- mentation and instructional design are two different fields with fundamentally different goals and while it may seem to be a simple matter to create training materials, a different set of skills is required for effective training materials. This paper outlines strategies that technical communicators can use to create more effective training materials.
onsider how you would complete this sentence: own initial forays into developing training materials, C“The goal of a technical communication product I can attest that my first “courses” were really just is to….” repackaged manuals with next and previous buttons and a few quiz questions thrown in for good measure. While you will receive a different answer from dif- Approaching instructional material from the per- ferent technical communicators, I would expect that spective of documentation and user assistance can most answers would coalesce around the idea that obviously lead to courses that are little better than the product should assist the user solve a problem tossing a manual to a learner and calling it a day. that is plaguing them right at that moment. Clear instructions on dealing with a particular issue are So what are some fundamental changes a technical one of the primary ways in which we assist users communicator can make to their mindset when solve their problems. These can be delivered through approaching instructional material? A few places to a manual, online help, tooltips, or any number of start: other avenues but their goal is the same: assist the user past their point of difficulty. • Think it terms of performance improvement. What learner behavior needs to change? • Make the learner an active participant in the A Change of Mindset process. Whether it’s e-learning or in-class training, how can you get the participant Needless to say, the goal of instructional design and involved? training is not to assist the user past the point of • Consider the goal of the learning. Should the difficulty. While much of technical documentation user recall something specific? Perform a may be considered reference material that should procedure? Solve a particular problem? Each be consulted in a time of need, training and the of these goals requires a different instruc- techniques instructional designers use to create tional approach. effective training are used to bring about a change in behaviour. Essentially, build a new pattern of behav- • What are the criteria for success? How will ior that is either completely new or replaces an old we evaluate success? pattern of behavior. This list is not exhaustive but it should help you So how can we change the way we as technical com- explore ways of presenting your training in a more municators approach training materials? From my effective manner.
109 Training and Research Writing Learning Objectives Upon the completion of this module, you should be able to identify the tools in the standard toolbox There is a significant amount of effort that goes issued to all service technicians.” into creating an effective training. These include learner analysis, needs analysis, and task analysis. Circling back, lets consider how this would help us Each of these could occupy a paper in their own create effective training. This learning objective right. However, many technical communicators have would: extensive experience in audience and and task anal- • Give us a way of assessing learner success at ysis so we can instead focus on one of the most effec- the end of the module. tive technique that technical communicators can use to make their training materials more effective. • Help us craft effective questions. For exam- This will also keep technical communicators from ple, instead of multiple choice question with straying into the habit of creating products designed a list of tools you might instead choose a to get users past the point of difficulty instead of matching question with pictures of tools and changing their behavior. accompanying words. • Help us craft effective content. For example, Effective learning objectives are one of your most you would include images and descriptions powerful tools to keep you focused. They will ensure of the tools. You would not include informa- your training material includes the appropriate tion about how they receive the tool box or material at the appropriate level. They will also the colour of the toolbox. help you formulate effective quiz questions and evaluations. Finally, they will allow you to assess the effectiveness of your course. In essence a learning objective is “a statement that tells what the learners A Different Profession should be able to do when they have completed a We have barely scratched the surface of what goes segment of instruction.” (Smith & Ragan, 2005, p. into making effective instructional content. This is 96). Note that the learner must change their behav- not surprising as instructional design is it’s own pro- ior, not simply get through the task: “Learning is a fession. But with organizations looking for technical cognitive process that leads to a capability that the communicators that can wear many hats and tech- learner did not possess prior to instruction.” (Smith nical communicators looking for new opportunities, & Ragan, 2005, p. 96). changing our mindset and then leveraging our area So what can we do to create effective learning objec- of expertise (writing!) today’s technical communica- tives? A good learning objective contains three parts. tor can significantly improve their training products and their increase their value to their company. • A stem. A stem is the first part of your learning objective and communicates at what point the objectives will be achieved. For Resources example: “At the end of this module, you will Smith, P.L., & Ragan, T. J., (2005). Instructional be able to…” Design. Hoboken, New Jersey: John Wiley & • A verb. An action verb that suggests the Sons Inc. form of assessment. While beyond the scope “Learning Objectives: Stems and Samples.” http:// of this document, note that different verbs www.educationoasis.com/instruction/bt/ are used for different outcomes. For exam- learning_objectives.htm ple, listing a set of tools would assess their knowledge of something while identifying Armstrong, Patricia. Bloom’s Taxonomy, Vanderbilt a set of tools would assess their analytical University. http://cft.vanderbilt.edu/ abilities. guides-sub-pages/blooms-taxonomy/ Waller, Kathy. Writing Instructional Objectives. • An learning statement. The learning http://www.naacls.org/docs/announcement/ statement sets out what the learner will need writing-objectives.pdf to do to demonstrate mastery of the material.
So a completed learning objective might look like this: “
110 2015 STC Technical Communication Summit Proceedings Moving into Instructional Design References
Smith, P.L., & Ragan, T. J., (2005). Instructional Design. Hoboken, New Jersey: John Wiley & Sons Inc.
Author Contact Information Stephen Van Esch E-learning Developer Ontario Clean Water Agency [email protected]
Author Biography
Stephen Van Esch is an instructional designer and e-learning developer for the Ontario Clean Water Agency. He has extensive technical communication experience and has worked in manufacturing, medical devices, and 3D modeling software. As an instructional designer, he works at creating effective distance education products for water and wastewa- ter treatment.
Stephen has a Masters degree in Education spe- cializing in Distance Education from Athabasca University.
2015 STC Technical Communication Summit Proceedings 111 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
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 2015 STC Technical Communication Summit 21–24 June 2015 • Columbus, Ohio © 2015 Society for Technical Communication
DEVELOPING AND DELIVERING SAMPLE PROJECTS AS USER ASSISTANCE Nicky Bleiel
In this paper, we will discuss what sample projects are, why they are useful, and how to develop and roll out them out. The basic concepts can be used to develop tutorials, train- ing, and even product demonstrations. In fact, planning a consistent experience across all of these will help your customers be more successful and save rework.
oftware user assistance includes all materials that • Learn what the product is capable of doing. Shelp to make users successful, including: Help, manuals, quick start guides, job aids, white papers, tutorials, videos, and sample projects. Sample proj- The Sample Project Team ects that customers can use to learn your application informally are not only educational; they can also Since sample projects have a number of objectives, serve as sales tools and proofs-of-concept. and (depending on the product) technical chal- lenges, the team working on the sample projects What is a sample project? They vary depending upon should span a number of departments. The Product the product. Sample projects can be (or include) Management, Marketing, Software Development, templates, completed projects (or parts of projects), Web Development, Quality Assurance, and modules, an interactive website, even code samples. Information Development departments should all be The best sample projects should demonstrate differ- included at various phases of the project. Everyone ent functionality, best practices, and features—while should agree on goals and responsibilities before remaining easy-to-use. beginning development.
Why Sample Projects are Useful Determining Objectives
Because customers can: The team needs to decide early in the planning process what concepts the sample projects should • Become comfortable in the user interface illustrate. Several concepts can be illustrated with quickly. careful planning, including: features, best practices, • Work in a real project with no fear. scenarios, product power (capabilities), ease-of-use, completed projects, end-user interaction, outputs, • Add their own data/content (depending on and development environments. the application). • Learn concepts more quickly. • Use a sample as a starting point for their Project Planning project, rather than beginning from scratch. (People can be intimidated by “blank When planning out your sample projects, keep the slates.”—Alan Cooper) following in mind:
113 Writing and Communication • The data or content must yield meaningful Distributing and Publicizing Samples results. If you want to demonstrate a number of features, make sure the sample has the Once samples are created, they need to be given appropriate amount of data or content. visibility. There are a number of ways to do this. A • Avoid proprietary content and graphics. few options: the product’s Getting Started Wizard, your website, the product interface, the online help/ • If you need a database, use one that is pub- documentation. You can publicize them via webcasts, licly available for download (if one of them email newsletters, blog posts and Tweets. fits your needs), if not, you may need to cre- ate one and make it available for download. After the initial rollout, you may want to ask your Consider a web-based sample if setup will be user community to contribute samples. Before the too complex. community is queried, the technology and guidelines • It is a good idea to establish themes for sam- for community samples will need to be developed by ples that you can use in other deliverables— the team, and a plan put in place to encourage, rec- for example, tutorials and training. The same ognize, and reward contributions. This may necessi- data/content can be used across projects. tate a new team member: the Community Manager. This will provide a consistent experience for your customers, as well as save development time. Recommended Reading • Downloading software and sample projects/ Cooper, Alan. About Face: The Essentials of User content should be as easy as possible. Interface Design, Wiley, 1995. • If code snippets will be needed, make sure Carliner, Saul. Informal Learning Basics, ASTD enough time is allotted to develop them. Press, 2012. Sierra, Kathy. Badass: Making Users Awesome, • Provide clear descriptions of the samples, as O’Reilly Media, 2015 well as instructions for using them. • For desktop products, make sure there is a backup included, or way to restore the Author Contact Information samples to their original state. One way to Nicky Bleiel handle this is to include the samples in two Watson Information Developer directories in the installation. IBM • If developing a web-based sample, determine 1710 Murray Avenue, Third Floor if a login will be needed and plan accordingly. Pittsburgh, PA 15217 Make sure the sample is tested on several +1.412.315.2148 browsers. Author Biography
Writing the Scripts Nicky Bleiel is a Watson Information Developer at IBM. She is Immediate Past President of the Society Every sample should have a script or outline before for Technical Communication and has 20 years of sample creation begins. All objectives should be experience writing and designing information for listed in the script so nothing is missed. When devel- software products in a variety of industries. She is a oping scripts, remember that scenarios should be popular speaker at many conferences, including the realistic, and familiar to the audience. Make sure the STC Summit, WritersUA, tcworld, CIDM (Content content/data developed will work in your scenarios Management Strategies/DITA North America), and (for example, if your software creates charts, make LavaCon; and has been published in STC’s Intercom, sure the data will create charts that are meaningful). tcworld magazine, ISTC Communicator, and more. When illustrating best practices, make sure to high- Learn more about her at www.nickybleiel.com. light those in the sample. You can use video, audio, Follow her on Twitter @nickybleiel. or any other relevant medium to augment your samples.
114 2015 STC Technical Communication Summit Proceedings 2015 STC Technical Communication Summit 21–24 June 2015 • Columbus, Ohio © 2015 Society for Technical Communication
CLEVER COPY FOR HAPPY USERS Lauren T. G. Colton
The wrong word or misplaced phrase can send users in the wrong direction (or away from your brand). Learn how to measure success, find meaning behind missteps, and maintain the standards your audience needs. Be clever—measured, intentional, and con- sistent—to build a community of happy users.
Context—what one thing, physical or semantic, Document the Organization & Project means in relation to another—shapes the outcome of a message. Text, in any context, affects user An organization’s culture shapes the message pro- experience; organizations can test copy to improve duced, and the message style alters who connects usability and reach business goals. The design of with a brand, as well as how they engage. There is communication bridges the art of exploration with at least one person behind every brand’s message. the science of analyzing ourselves, our audience, the Localized vocabularies appear based on geography, gaps between us, and how to evolve toward (and subject matter expertise, political beliefs, and other with) our audience. personal affiliations. A child learns labels and struc- tures (“this is a bird”) from the people around them, but no child asks “is this a bird or a car” to distin- Measure the Communicators guish the concepts.
Before an interaction begins, define yourself as an Linguistic biases and blind spots can come from organization and who you want to become, as well as experience as well as ambition. A copywriter with who your end user is and who they want to be next. a tight deadline could mistake structual familiarity A website is answering questions, such as “should I with situational corectness, and a Millenial is more vote for this candidate,” “is this a brand I trust,” and likely to consider “because” as sufficient to introduce “will I buy this widget.” The questions you lead users a verb or noun than a Baby Boomer. And high school to answer—“why don’t I have the same widget as the students who do not strongly identify with their Joneses?”—should prompt nodding heads and drive hometown, and want to leave after graduation, are project goals. less likely to display the regionalized language of their peers. Context is the map we use to navigate layers of perceptual and linguistic information: I am standing Consider the context and listen for the tone—vibrant, in my kitchen or checking luggage at the airport, I authoritative, curious, genuine—used by project have a fourth-grade reading level or a PhD in Top owners as well as trusted assistants. Record this Quark Physics. Spatial boundaries and sociocultural brand biography, and set a schedule to re-evaluate connections change what communication is more as you grow. effective in each interaction. Document Target Audiences
The user’s context will shape the meaning received from a message. Documenting and reevaluating users can guide message tactics as well as strategy. 115 Writing and Communication
Returning Users, Expert Level Rank: Second Description Existing customers who need quick access to advanced tools. Generally 30-40 years old, with high level of technical literacy. Logging in to com- plete work-related tasks. Your Message Your day is about to get easier. Their Goal Open personalized dashboard. Table 1. Define and rank target users.
Group current and target users into categories. Once as websites ask them to hold unfamiliar terms in grouped, both quantitative analytics and qualita- working memory, instead of using elements that tive research will help determine user profiles or are “intuitive” according to a particular social group. personas. “Meaning emerges at the confluence of a goal-di- rected actor-observer engaging with information Identify each category, their primary goal, and the directly in the environment,” according to Marsha main message for that user; rank the importance of Haverty. that group compared to other groups. While there can only be one first-priority audience, rank is a matter of priorities, not exclusion: online, every page Test for Surprises & Meaning is the front page for someone. Language shapes the user experience. Words are the Standardize course correction with scheduled reeval- geometry of our human relationships: the depth of uation of your, and their importance to changing our past experiences translated through the breadth organizational goals. of our connections and capabilities. But the message sent is only the starting point for a dialogue, and that engagement requires organizations to listen, and Anticipate Contextual Interference respond. Testing can help track what is happening, and—if done well—enlighten us on why. People are Both linguistic and perceptual information shape far more complex and interesting than the personas context, and the interpreted meaning of any message. we give them. Interactions balance the instinctual and visceral (perceptual information) with the higher cognitive load of the logical (linguistic information). Measure with Quantitative Testing
Social gaps between an organization and a user can What people do, and how much, can reveal road- create understanding gaps through differences in blocks between the speaker and listener. However, vocabulary or semantic structure. After deciding the measurements we track are data, which is not how much we are willing to bend the message to the same as information. Numbers only expose reach desired users, the social difference between what people are currently doing with what they have the speaker and listener can still potentially risk per- already seen. The usefulness of quantitative tests ceived brand sincerity. The message signal must be depends on using (1) measurements of actual value, stronger than the contextual noise for recipients to (2) an approach that translates inferences into obser- receive the intended meaning. Information engage- vations, and (3) driving the quantitative research ments must evolve to help users recognize the struc- agenda wil qualitative finding. ture, coordinate their behavior to the structure, and maintain coupling through intermittent and evolving • Reverse Card Sorting factors. Therefore, “tolerance for imprecision is a Categorization: Without seeing page content, design value” when a meaning disconnect can inter- can users correctly anticipate which page rupt or disrail an interaction. in a navigation structure would help them complete a provided task? If concepts are We increase the cognitive load of a web page by grouped with unexpected categories or labels, asking users to expend mental focus to find informa- finding information and features can be frus- tion or complete a task. User frustration increases trating to real users.
116 2015 STC Technical Communication Summit Proceedings Clever Copy for Happy Users
• Flesch Reading Ease instead of a large and anonymous crowd, and Understandability: How many years of consider if this message is worth their time. education does a user need to understand • The Mom Test the text? A busy doctor can benefit from the Genuine: If your mother heard you say this, same simplicity that reaches a patient, but would she call shenanigans? Members of a the patient with a 6th grade education will language community notice outsiders wear- not understand the full meaning articles with ing linguistic costumes, and making these a 32.0 readability score. gaps more obvious breeds distrust. • Cloze Deletion Test • Five Second Test Vocabulary: If one out of five words is Actionable: When shown a screen for five removed from a passage, can the target seconds, what do they remember drawing audience correctly fill in the blanks? Look their eye? The main call to action must be for patterns of missed words, and revisit sufficiently obvious for people with the body terminology when there is more than a 30% of human knowledge at their fingertips, but failure rate. limited time and attention. • A/B Testing • Pair Storytelling Performance: If similar groups are presented Clear: Can a user easily summarize a passage alternate variations—of the copy or the inter- of text? Patterns of missed or mistranslated face delivering that copy—which variation meaning can be corrected. Start by describ- performs better? The definition of “success” ing a task with general language, and ask a should be evaluated for more-insightful feed- user to talk through the rest of that task in back (receiving more clicks does not mean their own words. receiving the right clicks). • Day-After Recall • Heatmapping Memorable: A day after reading a passage, Expectations: When presented with an can users remember the call to action? A interface, do user expectations of anticipated simple hallway test can reveal if a message is conventions match the expectations of the “sticky” enough. internal team? What seems obvious to a copywriter who sat through project meetings • Usability Magnitude Estimation might not translate to users faced with a web Functional: How difficult do users say a task page. was to complete? Average the difference between pre-task estimation and post-task assesment to separate usability flaws from Analyze with Qualitative Testing marketing issues.
Discovering why something happens, and how to to fix problems, requires the open-ended questions of Build a Culture of Adaption qualitative research. Responding to insights requires an adaptive culture. • The Parking Lot Test It takes buy in from more than one person to turn Interesting: Would a person delay getting testing results into messages that reach the intended home from work to hear this message? audience with the intended meaning. Even freelanc- Imagine three people in a parking lot,
Your Org Want to be? End Who are you? User Guides current tactics Who are they? Sets foundation Guides ongoing strategy Want to be? Marketing Opportunity Table 2. Both the organization and the end user shape the message best suited for an interaction.
2015 STC Technical Communication Summit Proceedings 117 Writing and Communication
ers on a team of one need the support of clients to a consistent, professional message. For entire shift observations into next steps. organizations and specific projects, cross-functional teams can record and refer to the idiosyncrasies of subject-matter domain and marketing campaigns. Govern Communication Standards When you cannot use the standard terms of your Content governance is part policy and part proce- team, clearly define descriptive and useful vocab- dure, part strategy and part tactics. Be clear with ulary in a glossary. Other team members may be Plain Language, record and maintain a style guide highly educated in other areas, but if a “carousel” for a project team to reference, rank content “chunks” matters to the content manager, the meaning of “car- on each screen, and regularly reevaluate standards. ousel” will be important over the life of a project.
Use a Plain Language Guidelines Map Content Priority
Following the principles of Plain Language, copy can Ranking content is like the Highlander: “there can be easy to read, easy to use, and easy to understand be only one” top priority. For each key page, group the first time users encounter a text. The standard of information and features into digestible segments being “plain” requires understanding, planning, and such as a “buy now” button, a short list of related course correction, but it leads to clear meaning as blog posts, or a paragraph summarizing features of well as actionable copy. a car. When designers are ready to move into wire- framing, collaboration with content producers and • Speak to your audience. managers can be part of the decision. Starting with a ranking of content helps designers across a range of • Avoid jargon. desktop and mobile devices. • Give common words common meaning. For example, a website to sell widgets may rank “buy • Know which grammar rules matter. now” as top priority. The wireframe—a preliminary • Be precise. • Promote descriptions, demote exceptions. • Don’t hind your verbs. • Be actionable. • Use visual aides.
Maintain a Style Guide
Documenting the tone and style preferences for a project help groups of people come together with
Figure 1. A content-priority wireframe documents the client-desired focus across multiple screen resolutions.
118 2015 STC Technical Communication Summit Proceedings Clever Copy for Happy Users
sketch to set the design framework and page flow— Haverty, Marsha. “What We Mean by Meaning: New can maintain a project-defined rank: Structural Properties of IA.” Presentation at the Information Architecture Summit, 1. “Buy Now” button drive users to the online Minneapolis, MN, April 22-26, 2015. store. Hay, Steph. “Being Real Builds Trust.” A List Apart 2. Main menu to navigate site. (28 August 2012). http://alistapart.com/ 3. How our product will improve your life. article/being-real-builds-trust. Heath, Chip. Made to Stick: Why Some Ideas 4. Store contact information. Survive and Others Die (New York, NY: 5. Customize the widget options. Random House), 2007. 6. Customer testimonial. Highlander. DVD. Directed by Russell (1986; Troy, MI Anchor Bay Entertainment, 2002). 7. Statement about brand’s superior quality. Hinton, Andrew. Understanding Context Whether on a desktop, a tablet, a smartphone, or a (Sebastopol, CA: O’Reilly Media, Inc.), 2015. yet-uninvented screenport, planned content makes Ito, Rika & Dennis R. Preston. 1998. “Identity, delivery scalable and efficient. Current website traffic, discourse, & language variation.” Journal of organizational constraints, and project goals can all Language & Social Psychology 17, 4:465-83. guide and reshape content rank. Spool, Jared. “Is Design Metrically Opposed?” Presentation at the Information Architecture Standardize Reevaluation Summit, Minneapolis, MN, April 22-26, 2015. Who is accountable for maintaining content stan- Wachter-Boettcher, Sarah. Content Everywhere: dards, what is the definition of “successful” content Strategy and Structure for Future-Ready within the project or organization, and what is Content (New York, NY: Rosenfeld Media), the re-evaluation timetable? When everyone is 2012. responsible and every day is a reevaluation, no one Welchman, Lisa. Managing Chaos: Digital will govern standards, at any time. Define the role, Governance by Design (New York, NY: metrics, and schedule so that improving your best Rosenfeld Media), 2015. communication is built into every project. Wiebe, Joanna. CopyHackers Book 2: Formatting & the Essentials of Web Writing (Victoria, BC: References Copyhackers), 2011. Wiebe, Joanna. CopyHackers Book 4: Buttons & Colton, Lauren. “The Elegant Precision of Targeted, Click-Worthy Calls to Action (Victoria, BC: Actionable Language.” Presentation at Copyhackers), 2011. ConveyUX, Seattle, WA, February 5, 2014. Zeratsky, John. “5 principles for great interface Colton, Lauren. “Mobile User Interface Design” copywriting.” Google Ventures (18 February in Professional Mobile Application 2014). https://www.gv.com/lib/5-principles- Development (Indianapolis, IN: John Wiley for-great-interface-copywriting. & Sons, Inc., 2012), 89-115. Deutscher, Guy. Through the Language Glass: Why the World Looks Different in Other Author Contact Information Languages (New York, NY: Metropolitan Lauren Colton Books), 2010. Information Architect & Business Development “Federal Plain Language Guidelines.” plainlanguage. Strategist gov (1 March 2011). www.plainlanguage.gov/ Gravity Works Design & Development howto/guidelines/FederalPLGuidelines/ 1132 N. Washington FederalPLGuidelines.pdf. Lansing, MI 48895 +1.517.481.2218 Garner, Bryan. HBR Guide to Better Business Writing (Boston, MA: Harvard Business School Publishing), 2012.
2015 STC Technical Communication Summit Proceedings 119 Writing and Communication Author Biography
Lauren Colton uses clever content to help people engage with and understand within digital environ- ments. She manages cross-functional teams, shapes web and mobile messages, refines user experience, and trains clients to maintain a modern presence. Lauren collaborated on Professional Mobile Application Development (Wrox Press 2012), and she speaks across the country about creating precise, actionable interfaces. Learn more at www.gravity- worksdesign.com.
120 2015 STC Technical Communication Summit Proceedings 2015 STC Technical Communication Summit 21–24 June 2015 • Columbus, Ohio © 2015 Society for Technical Communication
HOW TO MAKE SENSE OF ANY MESS Abby Covert
Information architecture is the practice of choosing the ways in which we arrange the parts of something so that it’s whole will make sense to other people. Over the last few decades, information architecture has been a specialty at the core of fields like graphic design, way-finding design, information design, communication, editorial layout and website design (among countless others.) Traditionally information architecture is taught within specialties using heuristics and patterns -- sometimes they call it IA, but more often it is referred to by result based words like “language, hierarchy, clarity, intent, choices and understanding.”
There is an opportunity to look across these specialties in search of the ways in which information as a material is similar, regardless of what specialty or medium you might work in. Because we are increasingly seeing a world where these mediums are not only merging, but also being asked to work together to create new and unique user experiences.
This paper outlines some basic principles of theory behind understanding the architec- ture of information. It also proposes the hypothesis that information architecture is not a specialty in itself, but instead a skill set that would be useful for everyone to improve understanding and practice of.
ost people face messes made of information Since the mid nineties, pundits and thinkers have M(and people) everyday in their personal and/ warned us about the tsunami of information1 that is or work lives. Whether you are a designer, a technol- headed our way. They spoke of it like an alien attack ogist or a businessperson, these messes stem from from afar, but this was a mess we were in the process issues that are common regardless of the context for of creating ourselves. If predictions are correct, we the communication at hand. are not yet through this massive wave, in fact we are still watching its approach from shore. With it is an impending sense of anxiety about how we will deal Everything Has Information with all this information coming our way. Because of this wave, there is a growing need regardless of your Our world is a mess. Whether it be understanding job or place in the world to be able to make sense of your privacy rights on the latest social media chan- messes made of information. nel, figuring out how to send your children to college and still retire on time, or re-launching your busi- ness to be more “digital”. There are a lot of hoops to jump through, all of which are a growing part of the human dilemma.
121 Writing and Communication Thinking about Information Many people would take this bet. Why? Because as a Material is Hard everything they already know tells them that there were probably more cookies on that plate. Information is one of the most profound concepts The belief or non-belief that there were ever other involved in being human. Our ability to perceive and cookies on that plate is the information each viewer communicate our meaning to each other is a basic interprets from the way the cookies were arranged. complexity of our human minds that most people When we rearrange the cookies with the intent to move through their lives not thinking too much change how people interpret them, we’re architect- about. Yet it drives us. Everything we do relies on ing information. this critical skill of communicating with one another. While some users might consider it a fact that there For simplicities’ sake it is often thought that were other cookies on that plate at some point, information is all “things” that assist us with com- others may disagree because they never saw it with munication: text, pictures, and videos are the ready their own eyes. While some users might consider it examples in today’s online world. It is also often a fact that this arrangement of cookies means the misapprehended that information is anything that chocolate chip cookie is more popular, other users can be captured and filed away. But this isn’t quite might smell the oatmeal raisin wafting in the air and useful in many cases as it misses the most important believe that the chocolate chip cookie is not more aspect of information, which is perception. From the popular, but instead older than the oatmeal raisin standpoint of materiality, information can be looked cookies. While we can arrange things with the intent at as the subjective result of the content the user to communicate certain information, we can’t actu- perceives based on their context. ally make information. Our users do that for us.
Information vs. Data vs. Content. There is No Truth. Only Spin The content that you provide and the information a Once you remove the consistency between informa- user perceives can be slightly (or drastically) differ- tion and content, many people’s anxiety is increased ent. The synonymous use of the words data, content significantly. It turns out that when admitting to that and information doesn’t encourage those who make level of subjectivity, we are also being asked to give content or those who collect data to consider the up on concepts like “right and wrong” and “good and implications of connotation. Instead the makers of bad”. We are faced with the idea that all information content focus solely on the denotation at the detri- inherently has spin, because all information went ment of clarity. through the hands and minds of at least one other person on its way into our mind. While the differences may be slight between these three basic terms, they are important: • Data. The individual pieces of context, We Make and Use Things within knowledge, assumptions and questions each a Nested Set of Structures viewer considers to come to a conclusion regarding the world around them. Another complexity to this admission of subjectivity • Content. Whatever a user is interacting is the multitude of intertwingled2 connections that with, or as a maker, whatever you’re arrang- the things we make have to other things. These ing or sequencing. levels have different complexities, considerations and often are guided by different teams. Reconciling • Information. Each user’s unique interpre- and connecting the dots between these levels is often tation from the arrangement or sequence of the only way to truly make sense of a mess without content that they encounter. just adding another wrinkle to an already complex For example, imagine you’re looking into a bakery ecosystem. case. There’s one plate overflowing with oatmeal raisin cookies and another plate with one chocolate chip cookie. Would you bet a cookie that there used to be more chocolate chip cookies on that plate? 122 2015 STC Technical Communication Summit Proceedings How to Make Sense of Any Mess The following is a taxonomy for understanding the Objects Allow Us to Compare nested levels of place: Our Mental Models • Object. a specific thing. You can see people using their hands more in • Interface. a point where a user affects that conversations as the complexity of the topic gets thing. too much for their words alone. When we set out a • Location. a particular place or position. piece of paper between us and use it to visualize a shared model we can get much closer to our goal: • Journey. the steps in or between locations. agreement. • Structure. a configuration of objects and locations. We create objects like maps, diagrams, prototypes, and lists to share what we understand and perceive. • System. a set of structures working together. These objects represent our ideas, actions, and • Ecosystem. a collection of related systems. insights. When we reference objects during a conver- sation, we can go deeper and be more specific than Changes that happen at one of these levels can dras- verbalizing alone. tically impact things at other levels. The level you are working at, or being asked to work at, impacts what As an example, it’s much easier to teach someone you can see and therefore how you understand and about the inner-workings of a car engine with a pic- react to the problems you encounter. This is a critical ture, diagram, or working model. thing to understand. We don’t have the ability to make things in vacuums, therefore we must at least consider the broader implications of the choices we Messes Grow with Time make. There are plenty of reasons to not make sense of whatever mess you might be facing. Maybe it is There Are Always Politics “above your pay grade” or “can’t be fixed in the time Involved in Making Sense you have.” That’s fine, as long as you understand that the nature of messes is to grow when not tended Whether you are working on a small team or are to. deeply embedded in a large one, politics is a part of how we will arrange things to make sense to our Ways people ignore or hide the mess: audience. Everyone has an opinion, because every- • Fluff the visuals. Make it prettier and per- one has their own map of the way things work. That haps maybe no one will notice the mess. map is called their mental model and it influences their reaction to everything. Even while you are • Explain the Mess. Signage, tutorials, and reading this paper, your mental model is being refer- apologetic toned emails are ways to explain enced and perhaps slightly altered according to how the mess to users you are perceiving what you are reading. • Incentivize Dealing with Messes. Charging for a clearer solution, giving dis- Since everyone has there own model of the way counts to legacy users things work, working together can be fraught with difficulty, especially when the subject is too complex No matter what your excuse or alleviation mech- to easily grasp or there are many different paths or anism, the mess will still be there when you get options. It should be expected that we will have to around to it. work through these opinions, no matter how politi- cal a battle ahead, because without basic agreement, our mess will never make sense. Information Architectures Are Thought of in Three Critical Components
It is one of the core premises of IA that having a shared model for understanding the parts that make 2015 STC Technical Communication Summit Proceedings 123 Writing and Communication up a whole is always good for business. In this spirit, define a word with the variation of that same Dan Klyn of The Understanding Group proposed word. three critical components3 to be considered in infor- • Remember language is not just words. mation architecture. Icons, pictures, sounds, light, and even smells can be the language that is most effec- These three components are best thought of as tive in reaching our intent. While words are nested inside one another like those Russian dolls of not the only thing we need to be concerned subsequently smaller stature. with in understand our language, we must • Ontology. What do we mean when we say also remember that people often make up what we say? words for things that don’t have labels yet. This is called an uncontrolled vocabulary. • Taxonomy. What structures do we provide to make sure that meaning is found? • Watch out for linguistic insecurity. This is the all too common feeling of lan- • Choreography. How should language and guage being in the way of communicating structure change across channels and con- effectively with someone. Whether it is a texts to uphold the integrity of the intended colleague talking in jargon or an interface meaning? using overly technical speak, there are exam- ples of experiencing linguistic insecurity Ontology in everyone’s life. The important part is to remember how that feels and not make your The thing that’s most difficult about working with users, clients or co workers ever feel like that. other people is that language is merely short hand This is important because people experienc- for what we actually mean. Therefore many words ing linguistic insecurity are often difficult to and phrases can mean roughly the same thing. For communicate with. example, on an interface design the word “add” and “upload” could mean roughly the same thing. But the Taxonomy choice of which one to use is incredibly important. It may feel odd to ask a user to “Upload Blog Post”, There are two inseparable parts to everything we because they will be merely typing words into a box interact with: content and structure. One without and clicking an action to make it available publicly. the other is useless. Imagine if I were to rip all the In this case “Add Blog Post” probably feels more words out of your favorite book and dump them into right. Why? Because that choice helps users under- a pile on the floor. We can all agree this is no where stand what they will be asked to do next. near usable or transferable to another person as your favorite book. This is because the structure we give Our choice of language can drastically impact the to this content is what makes is the book you love. thing we make, yet all too often language is painted on after the fact. Ontology is the study of meaning. It The structure that we put our content in can drasti- involves looking deeply at what we mean and decid- cally affect the way people perceive our content. This ing that language would be best used to convey that also changes how we use the content that is provided. to our users. For example: you would never take a spoon from the “dirty spoons” bin in a cafe because of the effective To assure that your ontology is clear, consider the taxonomy of this environment. Imagine trying to fig- following tools: ure out which spoons are clean and which are dirty • Create a controlled vocabulary. A con- without the labels. trolled vocabulary is an agreed to documen- tation of language within a context of use. It is perhaps most important to remember that These are useful to think of both in terms of judgment is inherent in the ways that we group and words you say and words you don’t say. label things into systems for others to understand. The following are some lessons for assuring you • Define nested terms. Often there are are thinking about the taxonomy of what you are terms within the definition of a term that offering. actually need to be further defined for true clarity to be reached. Remember, never
124 2015 STC Technical Communication Summit Proceedings How to Make Sense of Any Mess
• LATCH4. According to Richard Saul website may be created for a single campaign for a Wurman, there are only five ways to organize single organization, yet each piece of content exists anything (Location, Alphabetical, Time, on its own channel. Category and Hierarchy. This may seem simple, but none of these is ever a “sure Context is the larger circumstance surrounding thing”—instead each has its own complexi- the moment of use. For example: A user seeing our ties and contexts of uselessness. Imagine a bus shelter ad and accessing our website via their phone book arranged by birthdate (time), or mobile device is a different context of use than a a grocery store arranged alphabetically by user typing in our URL via their desktop computer, main ingredient. or calling our 1800 number. • Facets. A facet is a individual piece of In the world of physical architecture, we choreo- knowledge that we understand about some- graph the movement of users through physical space thing, for example the season in which a by using cues that tell them what we intend for them certain type of vegetable is grown during is a to do there. They therefore know hallways are for facet we might call “Season”, we may also be transportation and rooms are for pausing around able to know that vegetable’s color, classifi- activity. Similarly, the content and structure of each cation, scientific name etc. Facets are the way room indicates the intended use of that space. Think we individualize a taxonomy to be appropri- about how many elements you would have to remove ate to the content being arranged. from a kitchen before a user would no longer know • Connotation vs. Denotation. Sometimes it was a kitchen just by entering it. This concept of how something is exactly defined doesn’t deciding how a space is arranged to communicate an matter as much as what something means intended use is called placemaking. to someone else. For example: tomatoes and many other types of produce are often “mis- This practice is important to understand, not just classified” on grocery store websites as veg- in physical places. Digital places also need to be etables. This isn’t because the designers of arranged in a way that communicates intent to the these sites are naïve to scientific taxonomic users of it. A good example of purposeful choreog- standards; instead it is likely because they raphy in digital placemaking would be the fact that understand that in their user’s mental model one cannot upload a picture to instagram.com nor tomatoes are treated more like vegetables edit a Medium.com article from a mobile device. It than like fruit. isn’t that that designers couldn’t have provided these options, or that they ran out of money to provide such basic functionality. It is that they thought the Choreography users ought not to use their products in these ways, as it would call their product’s intent into question. The way that a choreographer thinks about a dance is different than the way a dancer experiences it. One A product lacking basic desktop or mobile consis- impacts the other, but they would never be mistaken tency could get railed in a heuristic review of those for one another. Similarly, the way a information products, should the reviewer not take into account architecture is choreographed is different that the the intent of the makers. A user researcher could way a user experiences it. But it is the choice of avail- easily raise these as “things users keep asking for” in able moves that is important in order for the dancer both cases, but that too does not matter as much as to have the direction they need to get through the what it would mean if these slips in the integrity of performance. meaning were to take place.
When we talk about choreographing information Would Instagram be instant if you could upload from architectures, we are speaking to the idea that any your desktop? Would it open the flood gate of other system of language that we might lay out has to be features like albums turning it into something more flexible enough for many instances of use across resembling Flickr? channels and contexts. Would Medium articles be as profoundly thought- Channels are the mediums for communication that ful if people were allowed to type them with their we use to pass information around. For example: thumbs on-the-go? Would it just be another blog- A broadcast TV commercial, bus shelter ad and a
2015 STC Technical Communication Summit Proceedings 125 Writing and Communication ging platform based on that one tiny choreographic Author Biography adjustment? Abby Covert is an independent information architect In cases like this, asking the question is as important in New York City. She specializes in delivering a as the ability to find an answer. collaborative information architecture process and teaching those that she works with along the way.
Conclusion She speaks and writes under the pseudonym Abby the IA, focusing on sharing information architecture In conclusion, information architecture is all around content with those working within the design and us. It is baked into everything that we experience technology communities. She is the author of “How and a huge factor in the success of everything we as to Make Sense of Any Mess” a book about informa- makers bring to the world around us. tion architecture for everybody.
Information architecture always exists; it isn’t some- She teaches information architecture at The School thing you get to choose your way out of. of Visual Arts. She is also the current president of the Information Architecture Institute, a global non- Information architecture is not only for information profit membership organization focused on empow- architects to think about and improve upon. We are ering IA leadership, currently serving members in 73 all making this mess together, and it is going to take countries. all of us to make sense of it.
If you make anything, you are already practicing information architecture. Now that you have the baseline knowledge to think about IA more specifi- cally, you can improve on it iteratively.
Teach your children information architecture, it is this author’s opinion that IA will be a critical skill in every job of the future if we do this right and a forgotten art lost in a sea of meaningless nonsense if we get this wrong.
References
1Wurman, Richard Saul. Information Architects (Graphis Inc., 1997) 2Nelson, Ted. Computer Lib/Deam Machines (Nelson, 1974) 3Klyn, Dan. Understanding Information Architecture (TUG, 2014) 4Wurman, Richard Saul. Information Anxiety (Truong, 1989)
Author Contact Information Abby Covert Information Architect Abby the IA 147 Sullivan St. #2C New York, NY +1.617.504.2030
126 2015 STC Technical Communication Summit Proceedings 2015 STC Technical Communication Summit 21–24 June 2015 • Columbus, Ohio © 2015 Society for Technical Communication
PERFORMING A GLOBAL AUDIT Leah Guren, Fellow
Today’s business environment is global. Multiple markets, localization, different stan- dards; these are some of the challenges you may face when preparing your product docu- mentation. But is your content holding up to these challenges?
By performing a global audit, you can identify pain points that prevent your content from being global-ready. A global audit also identifies all potential problems in the localization process. By changing some of your documentation standards, you can improve both the source and the target documentation while streamlining the localization process.
What is a Global Audit? • improving internal processes that lead to problems during L10N A global audit is the process of identifying all content that is not appropriate for I18N (internationaliza- tion) or ready for L10N (localization): TC to the Rescue!
• I18N means creating a product (and its doc- Why does this matter? Content that is not glob- umentation) that is as acceptable as possible al-ready can mean product failure in some markets. to as wide an audience as possible, using During L10N, it can mean longer, costlier translation neutral examples and controlled English and even embarrassing mistakes! (sometimes referred to as simplified English). While some companies are already experienced at • L10N is exactly the opposite. It means localizing their products, many are not. The good creating a version of the product that is news is that this is your chance to be the hero. By appropriate for a specific market. This conducting a global audit, asking the right questions, includes translating the product interface and raising red flags on these problems, you can and documentation, and it may include mod- potentially save your company from making painful ifying the content (organization, topics, and and costly mistakes. even product features) as needed. Ideally, for L10N to be more effective, it should start We are the information professionals who under- from I18N sources. stand our products and their domains. We are also A global audit is simply an internal review of your the in-house linguistic experts. Therefore, we are existing documentation content, including: logically the right people to spearhead the effort to make our content global-ready. We are also the cor- • identifying potential problems rect point of contact with the L10N agencies. • correcting them • establishing improved standards (for exam- ple, making changes to your in-house style guide) to prevent the problems in the future
127 Writing and Communication How Do You Do a Global Audit? interactions may be confusing (or downright annoying) in print. Remember, humor never Start by reviewing your existing content, looking for translates well! the following things: 4. Review the graphics. Make sure that 1. Review the writing. Look for idiom, local the images you use are not problematic. expressions, and slang. I call this “we-centric” Seemingly innocent hand gestures in one writing. Remember that what is clear to you culture can be obscene in another. And those may not be clear to someone who is not a icons that make sense to you may be a bro- native speaker. Look for long sentences and ken metaphor in another country. Look at complex structure (such as nested clauses). the graphics themselves and make sure that Ideally, keep sentences under 13 words. the text is always a separate layer in the DTP Look for words being used in different ways tool, not inside the graphic. (a classic problem in English). For example, 5. Review the tool usage. L10N projects “Hose down the sidewalk with the hose” relies are often bogged down because the source too heavily on context and is difficult to content is so sloppy. Illegal and local format- understand and translate. Look for inconsis- ting, manual “tweaking” of content to force tencies in terminology (product and feature pages to fit, and other layout sins lead to names, technical terms, interface elements, expensive and time-consuming DTP fixes by and the verbs for user actions). Inconsistency the L10N agency. Remember that language is one of the biggest culprits for adding com- bloat will cause translated content to expand plexity and cost to L10N projects. by as much as 40%. Layout and design can 2. Review global standards. Look for units be problematic if you didn’t take into consid- of measurement. Make sure that you are eration what will happen if your content is using metric values. If necessary, you can translated to RTL (right-to-left) languages. list Imperial values parenthetically. Look at date and time formats. Americans are unique in listing month before date, leaving How Do You Use the Audit Results? dangerous ambiguity with number-only dates. For example, most people outside Once you have reviewed your existing content for of North America will interpret “11/08/15” those five general areas, you can start to apply the the 11th of August. To avoid ambiguity, use results: a modified ISO format (“08 November 1. Fix the writing problems. Obviously, the 2015”). And think of that casual reference problems that you found have to be fixed. to “8:00 pm ET” on your website; it is utterly But more than that, you have to update your confusing to users outside of North America. in-house style guide to reflect the new global Instead, use a 24-hour time (thus getting awareness. Take it a step further and develop rid of the confusing am/pm issue) and use training for the other writers and editors on a globally-recognized point of reference, your team. such as UTC (for example, “20:00 UTC -4”). Look for lack of parity with place names. For 2. Find a reputable L10N resource. If your example, I once had a client who had the company is not already localizing, you’ll need following as part of a use case: “Tony lives in to help find the right L10N agency. Look for Los Angeles, California, and Michelle lives translators who are mother-tongue in the in Paris, France.” He didn’t understand why target languages and have some experience this was so jolting and offensive to his users in your domain. (For example, someone who outside of the US. is a skilled translator of children’s literature is not necessarily the right person to trans- 3. Review the examples. If you have exam- late a medical device manual!) Get refer- ples in your documentation, make sure ences. Give them a short sample to translate that they are as “vanilla” (that is, bland and and then give the results to your company’s generic) as possible. Avoid cultural refer- rep in the target location. ences that would only make sense to some- one from your area. Above all, avoid humor. 3. Do usability testing. To make sure that What can be acceptable in face-to-face you have hit the target for I18N, find testers
128 2015 STC Technical Communication Summit Proceedings Performing a Global Audit
who match your personas but are not native Resources speakers. Put them through basic usability testing with the documentation, picking a Kohl, John R. The Global English Style Guide: few key procedures or some more difficult Writing Clear, Translatable Documentation conceptual topics. Have them read sections for a Global Market (Cary, NC: SAS Institute out loud. Ask them to explain back to you in Inc.), 2008. their own words. Look for anything you may have overlooked that is “we-centric” writing. Author Contact Information 4. Develop in-house support. Some people Leah Guren may not understand what you are trying to Owner do. Ultimately, you will not be able to make Cow TC content more global-ready if you do not Karmiel, Israel cultivate support from other stakeholders. www.cowtc.com Therefore, take the time to do your research. +972.544.853.473 Figure out what their pain points are and explain how your global audit can help those specific issues. For example, not everyone Author Biography cares about good writing or the user experi- ence! The regulatory person may care only Leah Guren is the owner/operator of Cow TC. She about compliance, while a product manager has been active in the field of technical commu- may be more concerned about TTM (time to nication since 1980 as a writer, manager, Help market). You have to be able to explain how author, and consultant. She now devotes her time global-ready content helps them. to usability consulting and TC training, primarily in Israel and Europe. Leah also teaches several 5. Start with a simple goal. Don’t try to do certificate courses for STC and is a popular speaker everything. Start with a small project. Tackle at various TC-related conferences around the world. a few simple things, such as terminology and Her clients are some of the top hi-tech companies global notation. Get input from R&D and internationally, including Intel, IBM, and Microsoft. Marketing so that the terms can be agreed on Leah is an STC Fellow. long before the interface is set. Ideally, you will be able to deliver a term list to the L10N agency and thus have a smoother, faster L10N process.
It Was a Painful Learning Curve!
My experiences have led me to recognize a few home truths:
• Problems that are obvious to us in TC are not obvious to others. • If you can’t “explain the pain” from the point of view of the stakeholders, you won’t get anywhere. • If you collect data about the cost and time of your existing L10N effort, you can more eas- ily prove the value of global-ready content. • And finally, let’s face it: some people are just afraid of the word “audit”!
2015 STC Technical Communication Summit Proceedings 129 Writing and Communication
130 2015 STC Technical Communication Summit Proceedings 2015 STC Technical Communication Summit 21–24 June 2015 • Columbus, Ohio © 2015 Society for Technical Communication
A CROSS-DISCIPLINE APPROACH TO CONTENT STRATEGY Denise Kadilak
Creating a content strategy does not mean simply figuring out how you plan to manage thousands of content-carrying topics or hundreds of chapter-bearing files. That is an ele- ment in the strategy equation, but because documentation teams nowadays do so much more than traditional “documentation” and work with so many different departments, a successful content strategy involves orchestrating a number of related elements. For example, determining what outside departments have a stake in the content you deliver, and what exactly should their input be? Also, what deliverables will best satisfy your users’ needs: videos, visual walk throughs, tip sheets, getting stated documentation, tradi- tional help, printed manuals, combination package? In this article, we will explore how to create a strategy that makes sure you effectively deliver the right information, in the right medium, while also satisfying the needs of all stakeholders.
Discovery The granularity of your test is also very important. For example, if you discover users prefer embedded n important first step in creating a strategy help be prepared to then provide them a couple of Ais implementing a meaningful discovery process. different embedded help options or if you discover This means engaging more than just your exter- training videos more popular than the written nal users; your internal stakeholders are equally instructions, be prepared to provide a couple differ- important. ent video styles—maybe one more interactive then the other. The best way to approach this is to plan Once you’ve identified all stakeholders, learn the for different stages in the discovery process, with the specific content needs of each. How you go about first stage focusing on the delivery medium and the this will vary. For external users, try working with second and maybe third focusing on the different the design or user experience teams in your com- style options available in the selected medium. Your pany. If these positions do not exist, support is also goal in this process—become fluent with the users’ a good option. You need to work with individuals general business operations to better satisfy their who regularly interact with clients be it answering user assistance needs. their questions, trying to understand their needs, or solving their problems. Ideally, through interactions Learning the needs of your internal users should be with one of these groups, you arrange your own con- easier. Simply reach out and talk to any potential tact with the external users. For example, approach internal user of your content. This step also involves the UX group to help you setup a “discovery” process learning who are your internal stakeholders? The that allows you to test various iterations of your most common answers to this question are market- content—embedded help vs. web-based help systems, ing, support, and training, but to be thorough, spend training videos vs. training documentation. some time investigating your corporate structure to
131 Writing and Communication
make sure you’re not overlooking any other groups content, and define each piece. You also must detail that may benefit from the content you create. reuse/sharing strategies, best practices/workflows, formatting, styles and tone. All require a good deal of The general advantages to a cross-discipline research and testing. approach are reduced duplication of effort, shared information, and leveraged expertise. Why have training and documentation create the same con- Tools tent? A successful content strategy understands and incorporates the training team’s needs. Sophisticated Next, determine how you plan to create these deliv- authoring tools make it easy to create and share erables. This step involves investigating and pricing content that satisfies the needs of both disciplines. tool sets that will allow you to create included deliv- The same is true with the knowledge base articles erables and support your information architecture. typically created by support teams. Often times over- In this step you probably also want to consider your taxed support teams cut and paste this content from current talent pool. For example, if your current pool the documentation set. Even worse, once created, of writers lack advanced technical skills you may these articles are often overlooked and not updated. want to avoid more advanced/complicated tool sets. Also, why struggle as a writer trying to created Your talent pool will also play a role in determining high-quality graphics for your visual deliverables. deliverables, unless of course you can leverage the Work with marketing. Not only may they be able to talents of other departments. Pricing plays a huge help you with graphics, they can probably also help role in determining tools. Make sure to win corpo- promote your various help deliverables—another rate approval for tools and pricing before including important consideration in any content strategy. them in your strategy.
Finally, create a governing method. You need to put Deliverables a process in place that makes sure the rules and pro- cess detailed in the strategy are followed. Important Once you identify all your users and their content governance considerations are who is responsible, needs, you next need to determine your deliverables. what are their powers/responsibilities, and how If you’ve done a good job identifying your users and strictly do they enforce. It is also helpful to define their needs, determining your deliverables should reporting and workflows for this process. be easy. Common deliverables include traditional documentation, help files, videos, video tutorials, and visual aids such as walk throughs or information Conclusion graphics. Try to include and test all options with your users during the discovery process and you As outlined in this article, creating a content strategy should come away from discovery knowing exactly is not simple; it involves a great deal of testing and what deliverables you want to provide. The key to research. However, if done correctly, one piece of the success with deliverables is not to include something strategy puzzle leads nicely into the next, and it all because it is new and “cool.” It must satisfy a need starts with understanding your users—both external identified during discovering. and internal—and working to satisfy their needs.
Architecture Author Contact Information Denise Kadilak Also, keeping in mind the needs of all identified Information Architect/Team Manager users, determine your content’s architecture: Blackbaud topic-based, book metaphor, something else? If 1020 Auburn Ave. you need to satisfy a variety of output types and Cleveland, OH 44113 formats—for example repurpose your help content +1.216.251.0716 to create training manuals—you probably want to go with something that allows granular output control like topic-based. If this is the case, you’ll then want to fill out your architectural plan identifying infor- mation types, such as concept, task, and reference
132 2015 STC Technical Communication Summit Proceedings A Cross-Discipline Approach to Content Strategy Author Biography
Denise Kadilak is an Information Architect/Team Manager with Blackbaud, Inc., headquartered in Charleston, SC. In her 17 years with the company, Denise’s responsibilities have ranged from that of a writer creating and maintaining 1000s of pages of user-end documentation to technical-project lead investigating new tools, best practices, and work- flows for a 22-member documentation team. She has presented at several international conferences, including WritersUA, the STC Summit, and CMS/ DITA North America on subjects ranging from structured authoring, advanced features in MadCap Flare, trends in Technical Communication, and content management. In addition to her position at Blackbaud, Denise is a part-time instructor at John Carroll University in Cleveland, OH, teaching the Technical Writing course included in the school’s Professional Writing program.
2015 STC Technical Communication Summit Proceedings 133 Writing and Communication
134 2015 STC Technical Communication Summit Proceedings 2015 STC Technical Communication Summit 21–24 June 2015 • Columbus, Ohio © 2015 Society for Technical Communication
HARDWARE WRITING: YOU CAN’T ALWAYS TOUCH IT Richard Lippincott, Associate Fellow
Technical communication in the later 20th and early 21st Centuries has been dominated by writing about software. Despite this, hardware offers a wide variety of subject matter in fields including technology, transportation, medical, security, robotics, networking, and telecommunications. Conventional wisdom states that hardware technical writing is easier than software technical writing, because hardware is tangible, it can be touched, devices can be turned on, picked up, turned over.
While this is true in some cases, the scenario falls short for hardware that is unrelated to the technology field. Aircraft, ships, transportation systems, high-energy devices, medical equipment, radar, and powerplant systems are all examples of highly complex hardware subjects that cannot be easily manipulated, operated, or sometimes even touched by the writer.
The skill set of clear communication and writing is equally applicable no matter what the subject matter, but hardware technical writing poses some unique challenges and respon- sibilities as well as the need for some specialized techniques.
Hardware Technical Writing Types Operator
ardware technical documentation is oriented Operator manuals are the most common type of Haround either doing something with the subject, hardware writing. The organization, principles, and or doing something to it. Operators will work with level of expected audience understanding is essen- the subject, field service/repair personnel will do tially the same as in software manuals. things to it. As a result, most hardware technical documentation falls into one of these four categories: Maintenance • Operator level documentation Maintenance manuals are aimed at more experi- • Maintenance manuals and documentation enced users, and typically they are repair techni- • Manufacturing Instructions cians tasked to do physical work on the systems. Frequently this work must be done at customer sites • Parts catalogues or remote locations. The user’s environment has to be considered. Large and complex hardware systems (for example locomotives) that break down usually
135 Writing and Communication
do so outdoors, so the user’s working conditions may Hardware manufacturing companies that want to be less than ideal. achieve or maintain ISO certification struggle with the problem of ensuring that hardware is built to Maintenance manuals are categorized by the level specific quality standards, that every component of complexity in the repairs, which in turn are is built the same way every time no matter which defined by the level of repair the user is permitted to technician performs the assembly. Companies perform. The three basic types of manuals are Field achieve this goal by requiring the technicians fol- level, Intermediate level, and Factory or Depot level. low approved written procedures. Manufacturing instructions have to be written down to the most • Field level manuals include only the sim- basic level, must be explain the entire assembly plest and most basic repairs to a unit, using a or manufacturing process, and must be detailed minimal amount of tools. Typical operations to a level that ensures a consistent and repeatable are the removal of faulty components (“Field process. Manufacturing instructions also normally Replaceable Units” or FRUs) and installation include complete lists of all the parts, all the con- of replacements. Field level manuals typi- sumables (lubricants, coatings, adhesives), and all cally also include preventive maintenance, the expendables (clips, safety wire) used in the pro- which is a set of regularly scheduled tasks cess of assembling the product. (for example fluid replacement) designed to keep the equipment operating properly. As a result, the manufacturing instructions often • Intermediate level manuals are aimed are some of the largest documentation sets for the at more experienced technicians and product. For example, a microwave-oven sized DNA include more significant repair techniques. analyzer currently in production by one company They include more extensive disassembly has an operator manual with a length of about 35 and system replacement tasks, as well as pages, but the manufacturing instructions total more detailed troubleshooting techniques. about 800 pages. Or, in aerospace, a set of mainte- Intermediate level manuals typically include nance manuals for a typical airliner may occupy 15 or wiring or other system schematics, the user’s 20 meters of shelf space but it’s not unusual for the tool set devices such as digital multimeters, manufacturing instructions (if printed) to exceed the torque wrenches, or boroscopes. Of the three weight of the completed aircraft. types of maintenance manuals, the inter- mediate manuals tend to contain the most complex procedural instructions. Parts Catalogues
• Factory or Depot level manuals are used Parts catalogues can be used at any level of operation when extensive rework or repair is needed. or maintenance, and often include a complete and These tasks can include complete rewiring, illustrated list of every component in the hardware fabrication of new parts, machining/grind- system. They are used to order specific replacement ing operations, and welding. Although the parts for the system. Parts catalogues are often level of task is deeper, in many cases these called by different names, depending on the stan- manuals do not contain detailed step-by-step dard or practice of the manufacturer, operator, or operations because the user is expected to both. Common names include “Illustrated Parts have knowledge and experience in the use of Breakdown” and “Repair Parts List.” the tools needed. For example, the instruc- tion to repair a broken tip of a turbine blade may only include tolerances and dimensions for grinding and smoothing, along with basic data on re-coating the component.
Manufacturing Instructions
Manufacturing instructions are the hidden gold mine of hardware technical writing.
Figure 1. ANSI Z535.6 Safety Admonition Levels
136 2015 STC Technical Communication Summit Proceedings Hardware Writing: You Can’t Always Touch It Safety Always ernment agency, contractor requirements, or other company policy. For example: Users of hardware manuals may be dealing with a series of potential health hazards including high • Documents for US Department of Defense voltage, moving parts, sharp edges, radiation, heat, contracts may be required to adhere to fumes, loud noises, confined space, and altitude. MIL-STD-38784 Users must be warned of the hazard, the potential • Commercial aerospace documents may be consequence, and ways to avoid the hazard. required to adhere to ATA 100 or iSpec 2200
ANSI Z535.6 describes one of several types of safety • Contractual requirements may dictate adher- admonition systems in common use. ence to ISO 29845:2011 or the 01.110 series • Automotive documentation may be required The style and format of an admonition system may to follow SAE standards be dictated by contractual requirements. For exam- ple, US DoD systems normally are required to follow While the specifications differ in detail, the purpose the system detailed in MIL-STD-38784. Commercial of each is to provide a common look and feel for aerospace documentation covering specific product or industry areas. In a bit of good news for technical communi- The importance of including adequate safety infor- cators, frequently these specifications already exist mation cannot be stressed enough. As an example, in in electronic formats that play well with XML the two worst aviation disasters in US history (at the driven publishing systems. time of this writing) were traced back to relatively minor errors in the technical documentation. The two accidents total more than 500 lost lives. Useful Skills
• Ability to read engineering drawings. Standards and Specifications • Familiarity with shop tools or machine processes. Hardware documentation format and layout may be controlled by specifications set out either by a gov- • Willingness to get hands dirty
Figure 2. Exploded View vs Ghost View of Jigsaw
2015 STC Technical Communication Summit Proceedings 137 Writing and Communication Illustrations more common, many suffer from hasty pro- duction and are of poor quality. A properly Illustrations in hardware documentation can prepared instructional video requires at convey a wide variety of details, including shape, least an hour of preparation time for each controls, individual parts, and areas of movement. minute of video time, it should be scripted in Once requiring the talents of a skilled artist, today advance, well-lit, and planned. technical communicators can produce complex and • Mobile devices can be used as aids in doc- detailed illustrations using common graphics tools. umentation in ways that go beyond just In addition to traditional tools such as Photoshop converting standard documentation to a or Adobe Illustrator, hardware design tools such as mobile format. For example, some Audi Solidworks can be paired with specialized graphics automobiles in Europe feature an owner’s tools that allow the creation of figures directly from manual coupled with an iPhone, the owner the solid model. aims the iPhone camera at a part of the car and the device automatically pulls up the Different styles of illustrations serve different pur- data in active video form. poses. In the examples shown below, the exploded view is best for showing all of the components in the • Augmented reality systems are already in use device, the ghost view is best for showing the relative in manufacturing. For example, Lockheed position of a subsystem in the device. Martin workers assembling some compo- nents of the F-35 Lightning II fighter air- plane use the Epson Moverio BT-200 system Future Trends to display all of the assembly information required. The technical documentation is Hardware documentation is the oldest form of tech- displayed as graphics and text seemingly in nical communication, the earliest known examples front of the user. are on clay tablets. As communication technology has changed, so has the method of delivery. For example: Conclusion
• Video is becoming more popular as a method Although sometimes given less respect than software of delivery. A well-produced video can documentation over the past few decades, hardware provide a better explanation than pages of documentation has a long history in technical com- text. While video presentations are becoming munication and will continue to be an important
Figure 3. Epson Movario BT-200 138 2015 STC Technical Communication Summit Proceedings Hardware Writing: You Can’t Always Touch It
part of the profession. Hardware developments are X-ray systems, and DNA analysis devices. Rick has the cutting edge of technology, and constant change a Bachelor of Science in Journalism from Ohio in hardware development means constant change University in Athens OH, and Master of Science in the documentation. The specialty of hardware in Technical Writing from Rensselaer Polytechnic documentation can be challenging and exciting…and, Institute in Troy, NY. Born and raised in New Jersey, sometimes after all, you really can touch it. Rick has been living in the northern metropolitan area of Boston MA since 1990. Rick’s hobbies include martial arts and scale model aircraft con- Resources struction, his favorite subjects in the latter being the same aircraft that he has written about. Rick is American National Standards Institute “ANSI Z535.6 also the author of the Squadron/Signal book C-5 American National Standard for Product Galaxy in Action, a history of the development and Safety Information in Product Manuals, operational history of the largest airplane in the US Instructions, and Other Collateral Materials.” Air Force inventory. http://www.nema.org/standards/z535/ pages/default.aspx International Standards Organization, “ISO 3864- 1:2011, Graphical symbols—Safety Colours and Safety Signs—Part 1: Design Principles for Safety signs and Safety Markings.” Acquisition Community Connection, “MIL- STD-38784—Standard Practice for Technical Manuals—General Style and Format Requirements.” https://acc.dau.mil/ CommunityBrowser.aspx?id=159776 Aerospace and Defense Industries Association of Europe—Standardization, “ASD SPEC 1000D.”
Author Contact Information Richard Lippincott Senior Technical Writer Analogic Corporation 8 Centennial Drive Peabody, MA +1.508.662.6428 [email protected]
Author Biography
Richard (Rick) Lippincott is an Associate Fellow in the STC and a Senior Technical Writer at Analogic Corporation, where he writes manufacturing pro- cedures. Rick is a past president of the STC Boston and New England chapters, and has also served as chapter Secretary, Treasurer, and social media man- ager. He has been a technical communicator for over 30 years, documenting both hardware and software products that include aircraft, turbine engines, ion implantation systems, RAID systems, voice messag- ing systems, core network switches, infrared imaging systems, high-energy transmission and backscatter
2015 STC Technical Communication Summit Proceedings 139 Writing and Communication
140 2015 STC Technical Communication Summit Proceedings 2015 STC Technical Communication Summit 21–24 June 2015 • Columbus, Ohio © 2015 Society for Technical Communication
WHAT I KNOW VERSUS REALITY Cindy Pao, Associate Fellow
Your company has a procedure in place for creating and updating policies and proce- dures, and enforcing that process is your job. How do you incorporate what’s really hap- pening at your company into the process?
nowing when you may be flexible in the process • Record the policy changes in the document Kand when you should not can help you publish history. this information in a timely and correct manner. • Update the document’s revised date and approver name. Policy Violations Prioritization You might work with a committee to review and update the employee handbook, which contains Some documents are very important and must be Human Resources’ and safety policies. If you are approved out of cycle. You can move them forward aware that managers and employees violate certain by being persistent: policies consistently, revise those policies with the following points in mind: • Send documents out of cycle rarely; avoid sending weekly if your approval cycle is • Remove unnecessary words and what if monthly. scenarios. • Set a shorter response time for out-of-cycle • Re-write the policy in Plain English. approvals. • Use active voice. • Send a reminder to or call outstanding • Emphasize what employees should do, rather approvers shortly before the deadline. than what they should not. • Use follow-up flags to remind yourself and the approvers about deadlines. Handling Approved Documents • Know which approvers you can pester. For those you should not pester, ask the policy There will be some policies that are not approved in submitter to help with reminders. your usual way. For example, policies about com- You might also work with people who want you to pany governance are often reviewed by subject mat- hurry, but then make you wait. Remember those ter experts at the C level and approved by the Board people well and document their projects well. of Directors. Work with these policies as follows: Handle future requests with care so that they do not • Apply the correct template and document disrupt other high-priority projects. styles. • Perform an abbreviated copy edit, checking for proper usage and grammar and the cor- rect use of certain terms only.
141 Writing and Communication Review Quality
Too often, reviewers do not take their responsibili- ties seriously enough, and inadequate or incorrect policies and procedures are approved and released. Later, the document must be retracted or updated to avoid policy or procedure violations. Encourage thorough reviews:
• Remind reviewers that they are the final step before approval. • Ask that non-management employees partic- ipate in the review by attempting to comply with the policy or trying to complete the task in the procedure. • Hold in-person review meetings where the reviewers discuss concerns and make changes together, rather than in silos. • Record the names of the reviewers and include this information when you send the document for approval.
Author Contact Information Cindy Pao Lead Technical Writer 20519 Autumn Terrace Lane Katy, Texas 77450 +1.281.773.3752
Author Biography
Cindy Pao is a Lead Technical Writer. She was previ- ously the Policies & Procedures Coordinator and was responsible for writing, editing, facilitating reviews and approvals, and publishing policies and proce- dures. She has also produced safety alerts and other user information for such industries as mortgage banking, oilfield services, and software.
Cindy is a member of the Community Affairs Committee for STC, as well as the immediate past president of the Houston chapter and immediate past co-manager of the Instructional Design & Learning SIG.
142 2015 STC Technical Communication Summit Proceedings 2015 STC Technical Communication Summit 21–24 June 2015 • Columbus, Ohio © 2015 Society for Technical Communication
DON’T JUST SHRINK IT; RETHINK IT! Marta Rauch, Associate Fellow, and Jennifer Stout
When writing for mobile and wearable products, as in life, you must evolve in order to thrive.
echnical communicators can enhance the mobile With such dramatic growth, it‘s more important than Tuser experience with a strategy that maximizes ever to provide mobile and wearable content that mobile content delivery. This workshop shares best meets users’ needs. practices for producing effective content to enhance the mobile user experience. First, we’ll share our tips and strategies for producing effective content. Then What is Mobile Content? you’ll put them into practice by producing your own mobile messages, product tours, and notifications. Mobile content includes all of the text on mobile screens, including tours, messages, notifications, and tips. Explosive Growth of Mobile and Wearables When you are working on mobile projects, you may also work on auxiliary content, such as:
The rapid proliferation of mobile and wearable • App store descriptions of features and devices brings opportunities for technical commu- updates nicators who create content and user assistance. Mobile devices and apps are enjoying explosive • Getting started, tips, and tricks growth: • Help topics, FAQs, and communities
• 1B smartphones shipped in 2014 (IDC) You may also be asked to host an end-user license • More than 1B Android devices have been agreement (EULA) as a web page and provide your sold, and we check them 100B times per day. development team with a link to the content for apps (The Verge) and app stores. • The Apple app store posted 1.2M apps and 75M downloads in 2014. (Tech Crunch) Prototypes Help You Create Wearable technology has been called Mobile 2.0, and Effective Mobile Content the wearables market is also growing quickly. When developing mobile content, using prototypes is • Wearable market growth is predicted to indispensable. Mobile prototypes identify issues and expand from $10M in 2014 to $300M in requirements early, while you still have time to adapt 2018. (Business Insider) the content. • In 2014, 27% of developers surveyed said they plan to create apps for wearables. Prototyping can help with: (Strategy Analytics) • Buy-in
143 Writing and Communication
• Requirements double-touch, drag, swipe, pinch, and spread. Review operating system guidelines for the mobile device you • Feedback are documenting to ensure that you use the correct • Scheduling term. • Quality Mobile message best practices: • Profit • Use a friendly, informal tone Prototypes can range from low-fidelity, such as a sketch on paper, to high-fidelity screens that closely • Be brief resemble the actual user interface. Consider starting • Use simple, clear language with low-fidelity prototypes, which are easier and cheaper to produce, to get early feedback. Then • Give a positive message without blaming the progress to increasingly high-fidelity prototypes for user usability tests. • Use the correct touch terminology for the operating system Prototypes, listed from low to high fidelity: • Give information to help users decide • Sketches between options • Templates • Integrate with design • Stencils • Design for delight
• Presentation software What to avoid in mobile messages: • HTML pages in mobile browsers • Complexity • Lengthiness Prototyping Exercises • Formality This workshop provides three exercises for proto- • Mimicking desktop text typing mobile and wearable content. We’ll do one exercise during the workshop. You can complete the other two exercises anytime. Scenario
Your product manager wants to add a feature for password reset. You are asked to mock up messages Exercise 1—Mobile Messages for the screen. You must present this to your team to get buy-in. Mobile messages provide guidance for mobile apps. A message can be an instruction, tip, feedback, status, error, or confirmation. Effective mobile messages are brief, simple, positive, and friendly. Mobile content must use the correct “touch” terminology, such as: touch, press, long press, tap,
Figure 1. Example—Touch Terminology Figure 2. Example—Password Reset
144 2015 STC Technical Communication Summit Proceedings Don’t Just Shrink It; Rethink It!
Instructions • Complexity
In the next 15 minutes, design messages to reset a mobile user’s password. Scenario
1. Join a small group. Your product manager shares product features for 2. Discuss and plan your strategy. a tour for a cloud drive app. You are asked to mock up content. You must present it to your team to get 3. Design and sketch. buy-in. Features from your PM:
4. Pick a spokesperson. • You can save all types of files on the cloud drive Your Turn • You can access your files from anywhere, anytime, from any device Share the content of your messages with other work- shop participants. • You can share your files with others and let them view, update, and download them
Exercise 2—Mobile Tours Instructions
A mobile tour summarizes main tasks and important In the next 15 minutes, prototype a tour that high- details for the app. Tours can give brief highlights lights features for a cloud drive app: of key features, introduce goals, and point out interactions. 1. Join a small group. 2. Discuss and plan your strategy. Best practices: 3. Design and sketch. • Be brief 4. Pick a spokesperson. • Be helpful
• Be engaging Your Turn • Highlight key features Share the content of your tour and show how • Show key actions it points out the key points from your product • Integrate with design manager.
What to avoid:
• Obviousness • Too many screens • Text-heaviness
Figure 3. Example—Key Features, Integrated with Design Figure 4. Example—Tour: Save, Share, Access
2015 STC Technical Communication Summit Proceedings 145 Writing and Communication Exercise 3—Notifications More detail is provided in Marta Rauch’s STC for Wearable Apps Intercom article and Summit presentation on wear- able technology:
A special consideration for wearable technology is • http://intercom.stc.org/2014/04/wearable- that people can wear devices all day. This makes technology-and-google-glass-why-it-matters/ it especially important to economize on content. Wearable notifications should be useful and provide • http://summit.stc.org/responsive/sum- needed information at the right time and place. They mit2014.htm#!Documents/wearabletechnol- should not annoy users as they go about their daily ogyandgoogleglasswhyitmatters.htm activities. Notifications should provide what users want or need, when they need it, on the device of Scenario their choosing. Your team is designing a fitness app with a smart- Edit especially ruthlessly for wearable content. As watch interface. You are asked to prototype a fitness you write and edit, ask: notification for the wearable device. You must pres- • What is the primary purpose of this screen? ent it to your team to get buy-in. • Will users know how to interact with it within three seconds? Instructions • What can be removed without changing the meaning? (Rachel Hinman, http://rachel- In the next 15 minutes, prototype the interface for hinman.com/) the wearable’s fitness app:
Notifications for wearables should be: 1. Join a small group. 2. Discuss and plan your strategy. • Useful 3. Design and sketch. • Timely 4. Pick a spokesperson. • Unobtrusive • Relevant Your Turn • Concise • Straightforward Share the content of your notification. • Visual • Adaptable • Accessible
Figure 6. Example—Wearable Fitness Notification
Conclusion
Mobile and wearable devices have unique require- ments for useful content. To ensure a positive customer experience, you must develop a suitable Figure 5. Example—Useful, Timely, Relevant, Concise, content strategy. As demonstrated in this workshop, Straightforward, Visual
146 2015 STC Technical Communication Summit Proceedings Don’t Just Shrink It; Rethink It!
a key to providing effective mobile and wearable Ultan O’Broin Wearables User Experience content is creating prototypes. Use the exercises Heuristics for the Enterprise in this workshop to create prototypes that embody these best practices: Prototyping Prototyping Tools http://keynotopia.com/ Stencils • Make messages positive and meaningful http://www.uistencils.com/ • Provide a tour to get users quickly on task Usability testing with paper prototypes http://vimeo. • Minimize content for wearables com/48675078 Paper Prototyping Paper In-Screen Prototyping For details on this workshop, see the slides on Streamlining Design with Paper SlideShare: http://www.slideshare.net/MartaRauch Prototyping Using paper prototyping to manage risk Resources Design Better and Faster with Rapid Prototyping Dan Roam, Back of the Napkin Marta’s Presentations and Publications
SlideShare, http://www.slideshare.net/MartaRauch Author Contact Information Pinterest boards on mobile and wearables http:// Marta Rauch pinterest.com/martarauch/ Senior Principal Developer Articles on mobile and wearables, Wearable Oracle Technology and Google Glass—Why It @martarauch Matters Mobile Usability Guidelines, Mobile Documentation Jennifer Stout Principal Technical Editor Mobile and Wearables Oracle Jakob Nielsen, Ralica Budiu, Mobile User @jennylauren123 Experience: Limitations and Strengths Katie Sherwin, Password Creation: 3 Ways to Make Author Biographies It Easier Don Norman, The Paradox of Wearable Marta Rauch is a senior principal information Technologies developer at Oracle, where she leads mobile, cloud, and REST API projects. She develops content Joe Welinske Developing User Assistance for Mobile strategy and content for iOS and Android apps on Apps Google Play and the Apple app store. Marta enjoys Rachel Hinman The Mobile Frontier, Practical participating in design jams and developer chal- Guide to Tactical Mobile Prototyping lenges for mobile apps, gamification, beacons, aug- Nathan Curtis Sketching for Understanding, The mented reality, and the next generation of mobile, Power of Sketches, 6 Tips for Organizing wearable technology. Sketched Artifacts A frequent presenter for conferences and webi- Lucidity Idea to App: How to Make a Mobile App nars, Marta has published mobile and wearable Mobile Luke Wrobleski, Josh Clark, Theresa Neil articles for IEEE, HCII, STC Intercom, and CIDM OS guidelines: iOS message guidelines, Android Best Practices. She contributed information to message guidelines, Operating Systems Developing User Assistance for Mobile Apps, by Joe Welinske, and her augmented reality topic appears Wearables in The Language of Content Strategy by Rahel Bailie and Scott Abel. Gartner’s Hype Cycle for Emerging Technologies, 2014 http://www.gartner.com/newsroom/ An STC Associate Fellow, Marta has received 15 STC id/2819918 awards for individual and team projects at Mary Meeker, Internet Trends 2014 http://www. the regional and international level. She is VP of STC kpcb.com/internet-trends Silicon Valley and a member of the STC Nominating
2015 STC Technical Communication Summit Proceedings 147 Writing and Communication
Committee. Marta holds a degree from Stanford University and a certificate from the University of California Extension.
Jennifer Stout is a principal technical editor at Oracle, where she encourages everyone to follow good writing practices and Oracle style guidelines whenever humanly possible. She is a member of the Oracle Style Guide Review Board, which produces the Oracle Style Guide. Before her technical career, Jenny was a copy editor at USA Today newspaper for 13 years, fighting grammar and punctuation errors one deadline at a time. Special interests include writ- ing for mobile devices and writing with accessibility in mind.
148 2015 STC Technical Communication Summit Proceedings 2015 STC Technical Communication Summit 21–24 June 2015 • Columbus, Ohio © 2015 Society for Technical Communication
GETTING STARTED IN POLICIES AND PROCEDURES: LESSONS LEARNED Jamye Sagan
When I first started working with policy and procedure documents, I had no idea where to begin. Over the years, I learned more about best practices and realized I still have much to learn. This paper describes six major lessons I learned about creating and main- taining policy/procedure documents.
mplementing or maintaining policy/procedure Lesson 2: Use a Document Template Idocuments is an enormous, yet rewarding respon- sibility. Here are six lessons I have learned about One element that greatly helped me in maintaining getting started in policies and procedures. our department’s policy/procedure library was establishing a standard document template. The template covered not only how information is pre- Lesson 1: Learn the lingo sented, but also how changes are documented, and when. Doing so enabled me to better manage content Although many people use the terms “policy” and and make it more user-friendly. “procedure” interchangeably, they actually represent two different concepts. In his book Establishing a • Templates save reading time by enabling the System of Policies and Procedures, Stephen Page reader to locate information more easily. defines policy as a “predetermined course of action • Templates add credibility and authority to a established as a guide toward accepted business document. Which document looks more offi- strategies and objectives” and procedure as a cial: the one with a heading and consistent “method by which a policy can be accomplished…the formatting, or the document that looks as if instructions necessary to carry out a policy state- were merely pasted into a document file with ment.” In other words, policy explains what must no formatting whatsoever? take place, and procedure states how to enforce the policy. • Templates make documents look more appealing and easier to read. This does not Being able to distinguish between policies and pro- mean having to use the splashiest graphics cedures makes the documentation process easier. In or the prettiest font. Documents still need to her presentation Defining Policy, Procedure, and be readable across all platforms, and convey Other Governing Documents, Emily Kowal explains the appropriate tone. For example, in our that having standard definitions of policy and proce- department, we incorporate our pharmacy dures makes it easier to author and edit documents, logo in the upper left corner of the page, as well as lends consistency and authority to the along with formatted title and most current documentation. date. At the end, we document when versions were updated, and what was changed.
All of these elements ultimately make it easier to both write and read policy/procedure documents.
149 Writing and Communication Lesson 3: Make Friends Overall, the flexible and customizable nature of with SharePoint SharePoint makes it an effective tool for hosting policy/procedure documents. Although any document-sharing platform can be used to host policy/procedure documents, I can best speak about SharePoint because we use it at Lesson 4: Spread the Word our company. Within our department site, I created After policy/procedure documents are created and/ a separate document library just for our policy/ or modified, users need to know about them so they procedure documents. This enabled me to create can begin following them. Use one or several of the custom settings that would not otherwise apply to following options to communicate information to other document libraries. The following SharePoint users: features are especially beneficial in managing policy/ procedure documents: • Email • Versioning. When versioning is enabled, • Memo the system saves prior versions each time • Conference Call / Webinar a new version of the document is uploaded. Flag the system to save all versions, not just • Webinar the last few. This is especially valuable in • Job Aid looking up which policy applied during a given timeframe. All I have to do is bring up • eLearning Module the version history and see which version • Instructor-Led Training was applicable during the given date. As to which option (or options) to choose: that is • Collaboration. To ensure that only one your call. Just consider time and available resources version is being edited at any given time, you have available, and work from there. If you require that documents be checked out require others’ assistance (such as instructional before they can be edited. Have the review design needs), take that into consideration. The committee work from the document library main point is to make sure people know what they instead of working from emailed copies. need to know. • Permission Levels. Take advantage of SharePoint’s capability to designate different levels of access. Designate who should have Lesson 5: Don’t Let the Document edit access to the documents; limit access to just those individuals. For everyone else, Grow Stale—Review! read-only access is sufficient. Once written, policy/procedure documents need • Major vs. minor (draft) versions. Select to be reviewed on a regular basis to make sure they the option to save both major and minor still apply. Page recommends that documents be (draft) versions. That way, your audience reviewed at least annually. Due to the dynamic can view the most current published version, nature of our department, many of our documents while you and your team can collaborate on are reviewed and edited more often than that. future drafts. • Categories. SharePoint enables one to eas- ily organize and display your documents by Lesson 6: Learn from Others category and sub-category. This is by far the biggest lesson I have learned. • Documenting revision history. When I first began managing our policy/procedure SharePoint enables you to document the library, I never realized so many policy and proce- revision history each time you check in a dure resources exist! I found Page’s book series on different version of the document. When you policies and procedures to be quite beneficial; he do view the version history of a policy/pro- provides a wealth of resources and links to templates cedure document, you can view the revision that I still find beneficial. history at-a-glance. Of course, this can be documented on the document itself as well.
150 2015 STC Technical Communication Summit Proceedings Getting Started in Policies and Procedures: Lessons Learned
Perhaps one of the best resources is by engaging with Page, Stephen B. Best Practices in Policies and other policy and procedure professionals. Procedures (Process Improvement Publishing), 2000. • Collaborate with peers in your department or company who also work in policies and pro- Page, Stephen B. Establishing a System of Policies cedures. Your human resources department and Procedures (Process Improvement may be able to help you with this. Publishing), 2002. • Join virtual groups. Search “policies and procedures” groups on Linked. If you belong Author Contact Information to the Society for Technical Communication, Jamye Sagan join the Policies and Procedures Special Pharmacy Communication Advisor Interest Group. Within this group, you can H-E-B subscribe to their discussion list and be able 646 South Flores Street to ask questions and seek advice from P&P South Building, 1st Floor professionals worldwide. +1.210.938.8526 In retrospect, I wish I had known about all these resources when I first started managing our policy/ Author Biography procedure library. Having all these examples at my fingertips would have made things so much easier. Jamye Sagan works for H-E-B, a retail grocery chain based in San Antonio, Texas. As the Pharmacy In conclusion, there is no one correct way to estab- Communication Advisor, she manages commu- lish policies and procedures in your department. nications between the corporate office and the The keys are consistency and communication. Just store pharmacies. She also maintains the policy/ remember: the primary goal is to generate content procedure documents for the Pharmacy department. that can be easily and readily referenced, so that A Senior Member of STC, Jamye serves in various users will remain compliant with policy. capacities, including Surveys and Membership Volunteer for the IDL SIG. She also serves as the SIG Liaison for the Community Affairs Committee, as Resources well as a member of the Community Achievement Awards/Pacesetter Award committees. Contact Kowal, Emily. Defining Policy, Procedure, and Other Jamye at [email protected]. Governing Documents (Proceedings, STC Summit Conference, 2013). Page, Stephen B. Achieving 100% Compliance of Policies & Procedures (Process Improvement Publishing), 2000. Page, Stephen B. Best Practices in Policies and Procedures (Process Improvement Publishing), 2000. Page, Stephen B. Establishing a System of Policies and Procedures (Process Improvement Publishing), 2002.
References
Kowal, Emily. Defining Policy, Procedure, and Other Governing Documents (Proceedings, STC Summit Conference, 2013). Page, Stephen B. Achieving 100% Compliance of Policies & Procedures (Process Improvement Publishing), 2000.
2015 STC Technical Communication Summit Proceedings 151 Writing and Communication
152 2015 STC Technical Communication Summit Proceedings 2015 STC Technical Communication Summit 21–24 June 2015 • Columbus, Ohio © 2015 Society for Technical Communication
TECHNOLOGY AND TOOLS IN POLICIES AND PROCEDURES Louise Tincher
This Policies and Procedures Progression session will provide an overview of some of the technology and tools we use to write, reviews, organize and deliver our policies and procedures.
Software • Establish appropriate life cycle(s) for review- ing and refreshing material hen we talk about technology for policies • Compare estimated costs to projected return Wand procedures, we’re mainly talking about on investment (ROI) computer software. These programs facilitate the key functions for developing and maintaining policies Organizations, industries and/or markets may dic- and procedures: tate project-specific tools:
• Word Processing • Applicable laws, regulations and standards • Reviewing • Lexicons or glossaries of standard terminology • Publishing • Taxonomies or classification systems • Archiving • Style guides for writers and editors Most companies use generic business software. Microsoft is the 600 pound gorilla in the room. • Professional organizations Major competitors include Adobe, Component One, Madcap, OpenOffice. Minor competitors also Author Contact Information abound. Specialized software offers benefits, but at a cost in time and money. The landscape changes daily. Louise Tincher Proposal Manager UES, Inc. Other Tools 3304 Carrier Drive Dayton, Ohio 45429 Use your technical communication skills to first +1.937.298.3978 identify the purpose, audience and requirements, and then address them effectively. Author Biography
Use business tools to align with organizational goals: Louise Tincher has 20 years of experience writing and editing a variety of technical documentation. • Identify key stakeholders who must be She creates order from chaos by developing and satisfied training others to follow well-designed processes and procedures that produce quality documentation. Her
153 Writing and Communication projects have ranged from A-Z (or at least S), includ- ing: avionics, electrical systems, financial services, government contracts, inventory tracking, hardware, logistics, maintenance, process improvement, pro- posals, requests for proposals, RFID, robotics, and software.
154 2015 STC Technical Communication Summit Proceedings Technology and Tools in Policies and Procedures
2015 STC Technical Communication Summit Proceedings 155 API DOCUMENTATION
Survival Strategies: Building Your First Website for API Documentation 157 Mary Linderman and Andrei Essaoulov 2015 STC Technical Communication Summit 21–24 June 2015 • Columbus, Ohio © 2015 Society for Technical Communication
SURVIVAL STRATEGIES: BUILDING YOUR FIRST WEBSITE FOR API DOCUMENTATION Mary Linderman and Andrei Essaoulov
Software companies are increasingly developing APIs to provide third-party developers with the ability to build custom solutions or to access their services and products. With this trend in the software industry, technical writers find their documentation projects expanding to include the creation of this highly technical content for developer audiences. Many technical writers must continue enhancing their skill sets while simultaneously developing API documentation with minimal resources. The initial development of a web- site for API documentation involves a steep learning curve, as well as multiple decisions about its construction that significantly affect its maintenance and evolution. This paper introduces basic concepts underlying the development of API documentation and explores strategies to facilitate building an API website.
riting developer documentation offers a unique used by third-party developers to build applications Wopportunity for you to expand your writing on an existing code base. These tools simplify this skills and enhance your technical expertise. You can process by providing public pieces of code that build developer documentation for your organization reference functionality already implemented by an by relying on those basic survival skills that you cur- internal development team. rently use to create rapport with your development teams, identify content needs for end-users, and You may also have come across the acronym SDK write for audiences with varying technical expertise. used to represent software development kit, which is This paper discusses key strategies for using minimal also a set of tools used by developers to build appli- resources to create documentation that provides cations with your API. In this case, the toolkit con- useful information and supports the adoption of sists of the libraries that contain the code referenced your API by third-party developers. These strategies by third-party developers, utilities used to facilitate include identifying key content, optimizing code implementing an application, code samples illustrat- samples, undertaking usability testing, and per- ing how to use your API, and other resources. forming other tasks that are crucial to the successful development of your website. In addition, you need to understand some of the basic concepts for object-oriented (OO) program- ming languages, since this paper focuses on docu- API? SDK? menting APIs used by languages, such C# or Java. When developers write code for OO languages, they Before we investigate building a web site, you need model it on real-world or business entities. They to understand some basic terminology commonly write the backend code that controls the function- used to discuss documentation written for software ality or features exposed in the API. For example, a developers. You may already be familiar with the development team might write an API for a technical acronym API used as an abbreviation for application communication application that tracks the activities programming interface. An API includes the tools of writers. One of the business entities is a technical writer so the team implements a class with this name, 157 API Documentation which acts like a template describing the features adoption strategy to make a stronger case for these and behaviors of a writer. The team also adds fields and other resources that you may need. or properties to the class that stores information about a writer, such as name, current project, and work hours. Next, the team adds methods, which Ramp up Your Technical Skills determine the behavior of a writer or tasks that a writer can perform, such as outlining, writing, and To ramp up your technical skills, begin by identifying proofreading. the programming language and other technologies used by your development team to build the API. A developer uses this class as a template to add You need this information to develop your technical multiple technical writers to the application, such vocabulary and the ability to read code samples. as Mary, Andrei, and so on. These individual repre- These skills help you formulate useful questions sentations of technical writers are called instances about the features implemented by your develop- of the technical writer class. A developer can then ment team, as well as facilitate your ability to write implement code that assigns the task of proofreading the documentation. to one of these instances, and supplies the name of the file for this task. As an API writer, you document Talk to your developers about the integrated devel- how to create these class instances, how to set their opment environment (IDE) that they use to write properties, and how to use the methods that control code, and install it on your computer. Similar to the their behavior. software used for developing documentation, an IDE provides developers with a specialized editor that facilitates writing code, and supports building the API Adoption Strategy libraries that they provide as part of the API. Just as you would investigate the GUI for user documen- An organization implements an API so that other tation, become familiar with the IDE to understand developers can consume it by writing their code, how developers build applications in the program- which references or uses its functionality. In most ming language used for your API. cases, organizations want external developers to use their API to extend product features, as well as While developing your technical skills may initially to encourage the use of their services or solutions. seem daunting, you have multiple options available As Jacobsen, Brail, and Woods point out in APIs: A for learning about the technology used by your Strategy Guide, API adoption has gained a major organization. Microsoft provides free videos and role in the business goals of companies, such as training materials in C#, while Oracle offers tuto- Twitter, Amazon, Netflix, and others. rials and training in Java. You may find the study guides for language certifications particularly useful As an API writer, you need to understand these goals, because they tend to provide succinct overviews of since a key element in this adoption process includes key language features. Watch the videos and use the information about how to use the API for building tutorials to set up your own development environ- custom applications or accessing the services that ment. Build the sample applications described in the it offers. This information provides an important tutorials so you can learn about features of the lan- context for your work, which you can use to frame guage and have fun running your own applications. the presentation of the API’s technical components. Depending on your current technical expertise, you Work with product management to identify the sig- may want to plan for about twenty hours of ramp up nificant features of the API so that you can highlight time to master terminology and to understand basic this functionality in the documentation, and support code samples. your organization’s adoption goals.
You also can use this API adoption strategy to Content for Your First API Website highlight your needs for resources to support doc- umentation development. When building out your One of the many advantages to ramping up your first website for an API, you may need additional technical skills is that you start to understand the developer time for reviewing content, writing code types of information, which developers may want in samples, and creating sample applications. You can order to work with your API. Your website content use this understanding of your organization’s API should meet the needs of developers with a range
158 2015 STC Technical Communication Summit Proceedings Survival Strategies: Building Your First Website for API Documentation
of technical expertise. This audience may include ignore explanatory content, no matter how well writ- entry-level developers just out of college; developers ten, in favor of your code samples. While complete with no prior background in the technology used by and accurate explanatory content is a significant your API; or experienced developers who just want component of your site, you also want to include information about a specific API feature. well-written code samples for all key API operations.
While websites differ based on the functionality pro- Work with your development team to establish a vided by the API, they generally include content that clear strategy for writing code samples, even though falls into these categories, which take into consider- this task may not be a priority for the team. Look for ation varying levels of technical expertise: opportunities to optimize the development of this content by reusing code from sample applications • Concept information - provides a high-level or QA test cases. In addition, consider the different overview of the features and architecture types of code samples that you need to illustrate of your API, as well as an explanation of operations in all the programming languages sup- the relationships between different classes ported by your API: represented in the object model. It may also discuss best practices for implementing fea- • Short snippets - use these code samples to tures and improving performance. illustrate a single feature discussed in your conceptual or overview content. This code • Tutorials or getting started materials - pro- may consist of two or three lines. vide instructions for installing the SDK and setting up a development environment. It • Codes samples for methods or classes - use may also include simple tutorials that pro- these codes samples to provide a detailed vide systematic instructions for implement- example of a specific API feature. They also ing a simple application or consuming some might be part of a step-by-step tutorial, and feature provided by your API. This content may consist of ten or more lines. offers the opportunity to illustrate best prac- • Sample applications - use these code samples tices for using your API, and to highlight its to illustrate complex projects and application user-friendly features. design with your API. These samples may • Code samples - includes short fragments of include multiple files. code and longer more detailed code samples, as well as complex code samples or even In addition, make sure that you format your code entire sample applications. samples using syntax highlighting to enhance readability. Syntax highlighting color-codes specific • Class libraries - provide reference material words and other elements in your code samples. generated from comments entered in the Different colors indicate code comments that aren’t source code during the development of the functional parts of the code, variables and other API. As an API writer, you may author this elements defined by a developer, and reserved words content, which provides descriptions of that are elements of the programming language. classes along with their properties and meth- ods. For example, you would use the class libraries to find the methods supported by Tools for Building Your Site the technical writer class, such as outlining or writing. You may face multiple constraints when choosing If you are familiar with DITA or content modeling, tools to build your site. The conceptual content, you may want to tag the different content types, and tutorials, and other explanatory material may be then use these techniques to structure the informa- written in the tool that you are currently using to tion on your site. develop user documentation, such as Madcap Flare, Robohelp, or other systems. However, you generate the class libraries, which provide your most signifi- Code Samples cant source of reference material, with a tool specific to the programming language used for the API. For example, Sandcastle is the tool frequently used to Show me, don’t tell me. This phrase sums up the generate class libraries for C#, while Javadoc tends significance of code samples for developers learning how to use your API. They may skim or outright 2015 STC Technical Communication Summit Proceedings 159 API Documentation
to be the tool of choice for the Java programming with these users, then consider asking co-workers language. to participate in the process. You can structure your usability tests to take only about an hour, which is a The repository that your organization uses to store minimal investment of time. the source code for your API may also have a signif- icant impact on how you provide comments for the Consider recruiting new hires for your development class libraries. Some organizations limit the access teams. Entry-level developers can provide insights of the technical writer to the source code, so that about content designed for users developing their adding comments becomes a complicated process. technical expertise. In contrast, more experienced The repository used to house the source code can new hires can provide insights about content devel- facilitate this process by providing a review workflow oped for the advanced users. If you are building the that allows writers and developers to collaborate first API documentation website for your organiza- when adding or editing comments. tion, recruit developers working on projects other than the API. They provide yet another perspective If you have the opportunity to choose the tools for about the documentation, since they are familiar your first website, consider these features during the with your products but not necessarily the API. Look evaluation process: for trends and commonalities in comments made across these groups, and make updates as necessary. • Authoring and collaboration capabilities • Learning curve for current and new docu- mentation team members What Is SEO? Why Do I Need It? • General web publishing functionality and support for community portals For developer communities, content must be acces- sible through Google or it might as well not exist. • Options for integrating with source control Developers tend to prefer searching for information products rather than browsing through a complex navigation • Flexible formatting and other customization structure no matter how well organized. They expect options to find information about public APIs by using one of the major search engines. For this reason, you • Costs for proprietary versus open source want to develop your familiarity with the concept of tools search engine optimization (SEO). • Compatibility with other tools used by your organization SEO includes the process of ensuring that your con- tent is discoverable by major search engines. While technical details of search algorithms are proprietary, Investigate Your User’s Experience you can find general information about how they index the content of your site, which helps you Usability testing provides important insights about understand how external search engines see your how developers navigate your website and their documentation. You can ensure that queries return expectations for it. In Rocket Surgery Made Easy, meaningful results by taking basic steps to optimize Steve Krug outlines a no frills approach to usability this process. testing that you can use to modify your site to improve the user experience. We learned that most When building your website, you also want to pay of our developers search rather than browse our doc- close attention to design details that may influence umentation site. Furthermore, they prefer to search the ability of developers to search your content. our content with Google, rather than use the search- Some page designs may make your web pages diffi- ing functionality available through the site itself. We cult to index, such those that use IFRAME elements. have used this information to identity site designs In addition, you may want to consider adding meta- that to facilitate this approach to searching. data or using other techniques to ensure that search engines return your pages. To perform your usability testing, you have variety of different options when it comes to recruiting test subjects. You may ideally want to recruit external developers, but if you aren’t able to begin testing
160 2015 STC Technical Communication Summit Proceedings Survival Strategies: Building Your First Website for API Documentation Look for automation opportunities session offered by Ed Marshall, Intercom’s API issue edited by Tom Johnson, and webinars hosted by When building your first API documentation website, Sarah Maddox. you may perform certain repetitive tasks manually, such as building the class libraries or publishing You can tailor all of the strategies discussed in this your site. These types of tasks offer the opportunity paper to your organizational goals, resources, and to utilize automation in your API documentation the needs of your external developers. They highlight project. fundamental challenges implicit in the development of a website for API documentation, while also offer- The generation of class libraries, the API reference ing opportunities to create a rich user experience information, lends itself to automation due to its for your developer community. Devise a successful highly structured content. The tools used to generate survival strategy! Don’t get voted off the island! this content include Sandcastle, Javadoc, Doxygen, and others, which provide output that can be pro- duced by an automated build process. Resources Jacobsen, Daniel, Greg Brail, and Dan Woods. APIs: The inclusion of code samples in your website offers A Strategy Guide (Sebastopol, CA: O’Reilly another opportunity for automation. You might ini- Media, Inc.), 2012. tially find yourself copying and pasting code samples into your documentation project. Consider working Krug, Steve. Rocket Surgery Made Easy, New with your development team to explore an auto- Riders, 2009. mated solution, which would eliminate your manual Linderman, Mary. “Lessons Learned as a Novice API steps and ensure that code samples in the website Writer.” Intercom (September 2014): 16-18. stay up-to-date. http://www.intercom.stc.org.
As you build and work with your site, continue to compile a list of tasks that might be automated when References you have the technical expertise or resources for De Kort, Wouter, Exam Ref 70-483: Programming these enhancements. Establish consistent naming in C# (Sebastopol, CA: O’Reilly Media, Inc.), conventions for files and other content elements to 2013. facilitate building integration points in your docu- mentation project as you have more resources and Greene, Jennifer, and Andrew Stellman. Head First opportunities to automate your processes. C#, 3rd Edition (Sebastopol, CA: O’Reilly Media, Inc.), 2013. Sierra, Kathy and Bert Bates. Head First Java, 2nd Strategize for the Future Edittion (Sebastopol, CA: O’Reilly Media, Inc.), 2005. Even as you build your first API documentation site, strategize for the next iteration of it. Look for Author Contact Information opportunities to balance your current goals for the site with its future growth and evolution, so that you Mary Linderman can be responsive to the development of new APIs. Senior API Writer For example, will your current toolset support the kCura LLC growth of your APIs? If not, can you structure your 231 South LaSalle Street, 8th Floor current content to simplify its migration to another Chicago, IL 60604 system? +1.872.800.6432
New trends in technical communications can also Andrei Essaoulov help you strategize for future iterations of your Senior API Writer site. Other sites hosting API documentation often kCura LLC provide useful insights about how you might want 231 South LaSalle Street, 8th Floor to continue evolving your site. In addition, technical Chicago, IL 60604 communicators continue to develop useful resources +1.312.870.5511 about writing API documentation, such as training
2015 STC Technical Communication Summit Proceedings 161 API Documentation Author Biography
Mary Linderman works on the development and maintenance of Relativity Developers website for the kCura in Chicago, IL. Mary worked on the initial development of the website, which provides third- party developers with API documentation. With over ten years of technical writing experience, she has gained insights about writing API documentation while working on the Developers website. Mary’s article “Lessons Learned as a Novice API Writer” appeared in the September 2014 issue of Intercom. She received her Masters degree in English from the University of Chicago.
Andrei Essaoulov joined kCura to support the ongoing development and enhancement of the API documentation hosted on the Relativity Developers website. Since 1999, he has worked as a technical writer for companies like as SPSS, IBM, and kCura. He received his Masters degree in English from Illinois State University.
162 2015 STC Technical Communication Summit Proceedings Survival Strategies: Building Your First Website for API Documentation
2015 STC Technical Communication Summit Proceedings 163 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 2015 STC Technical Communication Summit 21–24 June 2015 • Columbus, Ohio © 2015 Society for Technical Communication
WINNING THE PROJECT WITH AN EFFECTIVE PROPOSAL Alisa Bonsignore
Proposals: they’re more than just a project pitch. They can demonstrate your confidence and competence, establish the guidelines for a successful project, and help you cover your… assets. A well-crafted project proposal will help you inform, compete and establish the prarameters that help to keep your sanity intact, and ensure that you get paid on time—even if the project goes haywire.
[This information is not intended to replace the More Detail is Better advice of a legal processional. Please consult one in your area.] In most companies, projects of a decent dollar amount require the signature of an executive, some- roposals do more than set your price. They estab- one in Finance, or both. Deliver a detailed proposal Plish the guidelines for the project, covering every- that not only addresses the topics covered by the thing from deadlines to payment terms. Because they client contact, but also highlights every conceivable are negotiated in moments of calm—not during the element that might be necessary to push that pro- chaos of an emergency or deadline—a well-defined posal through the hierarchy and get the signatures proposal ensures that both sides enter into the rela- needed. tionship with rational expectations.
Negotiate! Legwork: Do Your Research Some will say that large companies won’t negotiate. The more knowledge that you have going into a proj- Not so! Even multinational, multi-billion-dollar ect, the more you are able to keep things from going corporations will negotiate pricing, payment terms, off the rails. Even a 15-minute discovery call can deadlines and responsibilities. Stick to your guns uncover details that don’t appear in a written project and be prepared to walk away if something doesn’t plan. Listen for the nuance as the prospective client work for you. talks. Who or what are the obstacles to success? Why this type of project? Why now? Why isn’t this being handled internally? Who’s driving the project? What is the underlying need? What is the available budget Create a Template to get this done? By listening to the pauses, the clar- ifications and the asides, you’ll quickly identify red When you use a proposal template, you are less likely flags, internal politics, and expectations. to leave out critical elements. A good template will include:
• An expiration date for the proposal • A start date for the project • A project timeline
165 Consulting and Small Business Management
• The scope of your services: research, writing, in the areas of medical devices, pharmaceuticals/ editing genomics, network security and healthcare IT. She has been a member of the American Medical Writers • The goals of the project: are we on the same Association (AMWA), the Society for Technical page? Communication (STC), the Public Relations Society • Limitations and recommendations of America (PRSA) Health Academy, and the San Francisco Chapter of the International Association of • Review and approval Business Communicators (IABC). • If flat rate: how many rounds of revision are included She has spoken about professional development to audiences at the Creative Freelancer Conference, the • When invoices will be submitted American Society of Journalists and Authors (ASJA), • Payment terms IABC, STC and AMWA. • Scope changes and rush fees • Signature page • Addendum: who are you, and why are you worth it?
Conclusion
Follow the steps for negotiating a proposal and you’ll have better client experiences.
• Talk to a lawyer • Identify what’s important to you (personally and legally) • Create a template • Make them sign every time
Author Contact Information Alisa Bonsignore Writer & Strategist Clarifying Complex Ideas [email protected] +1.408.256.0621
Author Biography
Alisa’s experience can be summarized in four words: she clarifies complex ideas. More than just a writer, Alisa’s extensive research experience is applied to all of her client work. She analyzes competitors and industry trends to gain the strategic insights needed to place each project into a broader context. The result: addressing customers’ real needs instead of recreating the same materials year after year.
Alisa’s experience spans several industries over the course of two decades, and includes companies
166 2015 STC Technical Communication Summit Proceedings 2015 STC Technical Communication Summit 21–24 June 2015 • Columbus, Ohio © 2015 Society for Technical Communication
CONTRACT OR CAPTIVE: WHICH IS RIGHT FOR YOU? Brenda Huettner, Fellow
What’s the ideal job look like? The answer, of course, is “it depends”. Ideal will vary from person to person, from job to job. From full time work for a large company to freelancing, this paper will look at the types of employment common in today’s fast-paced world, and identify some pros and cons for each. We’ll also go through a checklist of qualities, inter- ests, and work styles to help you identify which format is best for your specific situation.
eciding where and how you want to live and and sometimes limited benefits such as holiday pay Dwork isn’t easy. Some people prefer to work or retirement benefits if you work more than so alone; others prefer to work in groups. Some people many hours in a year. But this type of job usually like to maintain a lot of control over what they do; has a pre-defined end date – it’s just for the summer others like to have a lot of guidance. or the holiday season or while someone else is out on sick leave. The company still deducts taxes from the And, sometimes, you need to take into consideration employee salary. things other than the workplace itself – there are lifestyle and family issues that often require choices A part-time employee works directly for a com- you might not have otherwise made. pany, but because the job is less than 40 hours a week, many traditional benefits (like holiday pay or retirement benefits) are not always included. The Know Your Options company still deducts taxes from the employee salary. The workplace is more varied now than ever, with a wide range of employment types and corporate job An agency employee sometimes looks like a offerings. Before you make any decision, you need temporary employee or a contractor, but is actually to understand what some of the options are.
Work Status
There are lots of different words for the status of a worker within a company. Most people think of “employee” as the traditional deal: a full time job that offers benefits like insurance, retirement assistance, and vacation pay. This has been a standard for a lot of people for a lot of years. But it isn’t the only way to be “captive”.
A temporary employee works directly for a com- Figure 1. There are many different ways to describe the pany and gets salary (usually hourly), withheld taxes, status of a worker.
167 Consulting and Small Business Management
an employee of a different company (the agency) • Paid vacation, holidays, sick time and as such, would get the holiday, retirement, and • Employer provides insurance options other benefits of being an employee. The agency is responsible for deducting taxes. It’s usually hourly • Employer helps with retirement funds work, with a variety of clients, and can be very steady if you are good at what you do and have a good rela- tionship within the agency. Compare and Contrast: Taxes and Admin
A contract employee (or contractor) works Contract directly for a company for a set period of time for a • Must always be looking for next client or set salary but no benefits. In theory, this allows the opportunity salary to be higher (though it doesn’t always work that way). The employment agreement is set out in • Responsible for paying estimated taxes a contract that can be long or short term, but always (1099) has an end date, that can be hourly or weekly or by • Responsible for 100% of Social Security milestone. The contractor is responsible for paying taxes and often for other expenses. • Must submit invoices, sometimes several times A consultant generally advises about a specific job • Captive or topic, often recommending tasks that someone else will actually carry out. The pay is usually flat- • You usually know what you’ll be doing next rate – that is, a single amount for a specific job. year Consultants often get higher pay for more experience, • Employer withholds taxes (W-2) and it’s unlikely anyone would start out this way. • Employer pays 50% of Social Security tax A freelancer does a specific task, think “magazine • Some companies require time cards, status article” or “white paper”, for a specific amount of reports money (not tied to the amount of time it takes).
But for the purposes of this paper, we’ll consider Compare and Contrast: Legalities Contract to be any of the jobs that aren’t direct employees for a single company. Contract
• It isn’t called “contract” for nothing! You Compare and Contrast: Money and Benefits need one for EVERY job • You can negotiate which rights belong to you Contract and to the client • Higher Hourly Rate • Be careful of your status! Tax laws vary, and • Must pay expenses (but they’re deductible) the IRS keeps a close eye on contractors • Pay for own professional development (train- Not generally covered by labor laws ing, conferences, etc.) Captive • No pay for time off • Must arrange and pay for insurance • Employee Handbook (if any) spells out what you need to know • Don’t forget retirement! • Employer usually owns all rights to every- Captive thing you do
• Steadier rate of pay • As an employee, you have certain rights (IRS vs. Microsoft) • Employer pays expenses • Laws exist for things like overtime, breaks, • Employer (often) pays for professional protection from unfair termination development
168 2015 STC Technical Communication Summit Proceedings Contract or Captive: Which Is Right for You?
Compare and Contrast: Time Off • Do you have a cash reserve so you can you pay your bills while you’re getting Contract started? • Take as much vacation as you want, when • Are you disciplined about saving for a YOU want it rainy day or during down time? • Vacation, sick time, and holidays are unpaid • Do you have a home office and all the equipment you’ll need? Home office can • Unpaid time between assignments be a range of things – from kitchen table to Captive separate building. Some jobs want you in their office, others don’t. • Predefined number of vacation days, and • Do you have or are you willing to buy sometimes sick days the required software packages? For • Employer pays for vacation, holidays, sick contractors, as for companies, this is an days ongoing business expense, keeping up with latest releases and new types of software. • No unpaid “down time” • Can you accurately estimate how long it takes you to perform specific tasks? Know Yourself Estimating is a learned skill—the more you do the better you get at it. You might lose Once you’ve got a good handle on the types of work jobs (if bid too high or too many hours) or available, you need to ask yourself some pointed lose money (if too low) until you get it right. questions before determining whether you’re better • Are you covered under an insurance suited as a contractor or an employee. plan? You’ll need all kinds of insurance – health, dental, life, but also (sometimes) Pop Quiz! Count your “YES” answers: errors & omissions or other liability plans. • Are you self-disciplined? If you have a As a contractor, there’s usually no worker’s deadline, do you do a little everyday or put comp, no unemployment insurance. off until almost due? Would you sit down • Are you good at paperwork? You’ll need to work if no one is watching you? Can you to do your own book keeping, invoicing, get the job done if it is a nice sunny day or taxes, state filings, and more. the kids want to swim or the dishes need washing? Is it hard to distract you from the • Are you good at networking? This is task at hand? more than just going out to an occasional meeting, it also includes things like telling • Do you get along with different types people how good you are at your job. of people? Even if you’re working by your- self, you still need to convince the client you • Do you have a wide range of experi- are the man or woman for the job, get info ence and tools knowledge? Companies out of SMEs (same as employee, deal with are more likely to hire contractors who accounting/bill payers, and often a “per- already have the skills they’re seeking. manent” staff who may be thrilled you are • Are you flexible about when you work? helping but may also resent you. This could be late nights or early mornings • Do you like working by yourself? This (think India time zone at 12.5 hours differ- may seem contradictory to getting along well ence) or could be weekends. with others, but you need both skilss to be • Are you flexible about how much you a successful contractor. You don’t usually work? There might be no work at all for have a team of people to help you. weeks and then a month or two of 80-hour • Are you good at planning your time? weeks. You’ll need to schedule your own time, learn • Are you flexible about the kind of work to prioritize, particularly if you have multiple you do? If you’re an editor, you might need projects . to sometimes write (and vice versa).
2015 STC Technical Communication Summit Proceedings 169 Consulting and Small Business Management
• Can you handle many tasks at once? Author Biography While this one certainly includes things like working on multiple projects or documents Brenda Huettner is an independent technical com- or clients (as employees sometimes have to munication consultant specializing in increasing do), it also means that sometimes you need her client’s awareness of the benefits of quality doc- to be writing but also marketing your busi- umentation. An active member of the professional ness or invoicing. community in the Tucson area, Brenda has worked as a technical writer, technical editor, trainer, usabil- • Do you have a strong personal support ity consultant, documentation department manager, system? Support system – family, esp. Help author, content developer, graphic artist, and when working at home, need to give you webmaster. She’s written a wide variety of content space/time/quiet or whatever you need. for audiences of end-users, programmers, and engi- • Are you good at what you do? A contrac- neers. In addition to contract work through her own tor’s success is dependent on repeat business consulting company, P-N Designs, Inc., she main- and referrals. tains three Web sites and has several commercially published books in print. • Do you enjoy what you do? None of this will work without passion. She’s a principal of Microwaves101.com, an online encyclopedia of microwave engineering knowledge. Brenda is a Fellow of the Society for Technical Communication, and a Senior Member of IEEE, active in the Professional Communication Society, the Technical and Engineering Management Society, the Microwave Tools and Techniques Society, and the Tucson section. She’s also a member of the Usability Professionals Association and the Interaction Design Association. Brenda has pub- lished several books and articles, and presented half- day, full-day, and multi-day courses on writing, proj- ect management, usability, and career management.
Figure 2. Add up your yeses to see how you scored.
If you decide you DO want to pursue contracting, note that there are different types of work arounds for each question that you might have answered “no”. For example, if you’re not good at bookkeeping you can hire someone. If you’re not good at marketing yourself, you can work through a recruiter. No home office? Start with onsite work.
Finally, whatever you decide today does not have to be a permanent state. The beauty of today’s multi-faceted work landscape is that you can try dif- ferent approaches until you find what works for you.
Author Contact Information Brenda Huettner P-N Designs, Inc. 8987 E. Tanque Verde #309-155 Tucson AZ 85749 [email protected]
170 2015 STC Technical Communication Summit Proceedings
2015 STC Technical Communication Summit Proceedings 171
