2015 Technical Communication Summit Proceedings

Society for Technical Communication

Summit Proceedings 21–24 June 2015 Columbus, Ohio



#STC15 www.stc.org summit.stc.org 1



Notice The papers published in these Proceedings were reproduced from originals furnished by the authors. The opinions expressed and integrity of the information are the responsibility of the authors and not the Society for Technical Communication (STC). STC grants permission to educators and academic libraries to distribute articles from these Proceedings for classroom purposes. There is no charge to these institutions provided they give credit to the author, the Proceedings, and STC. All others must request permission. All product and company names herein are the property of their respective owners. © 2015 Society for Technical Communication

Contact Information Society for Technical Communication 9401 Lee Highway Suite 300 Fairfax, VA 22031 +1.703.522.4114 +1.703.522.2075 (fax) www.stc.org

Colophon This publication was produced using Adobe InDesign CS6. The heading typefaces used are Helvetica, Helvetica Condensed, and Helvetica Ultra Condensed by Linotype and licensed through Adobe. The text is set in Georgia, which is licensed through Microsoft. This Proceedings publication was compiled and designed by Michael Opsteegh.



2015 Technical Communication Summit Committee The Society for Technical Communication’s 62nd Annual Conference focuses on important trends in our profession. This publication contains papers submitted in support of the 2015 Summit conference sessions. This year’s conference is the result of the efforts of many individuals, including the Conference Manager, Program Advisory Committee, and staff of STC.

Conference Chair Chris Hester

Program Co-manager

Karen Bachmann, Perficient

Program Co-manager

Pam Estes Brewer, Mercer University

Track Managers Art, Design, and Visual Communication Adam Evans, kCura

Leadership and Management/ Consulting and Small Business Management Jamie Gillenwater, Transcend Text, LLC

Writing and Communication Michelle Despres, CQG

Tools and Technology/API Documentation Craig Baehr, Texas Tech University

Training and Research Adriane Hunt, CA Technologies

Technical Communication Summit program, session, and conference information can be found on Lanyard at http://lanyrd.com/2015/stc15. Slides from the presentations can be found on Slideshare at http://www.slideshare.net/tag/stc15.

2015 STC Technical Communication Summit Proceedings

i



ii

2015 STC Technical Communication Summit Proceedings

TABLE OF CONTENTS Art, Design, and Visual Communication BPMN Basics: What You Need to Know for Your Content Strategy 1 Jackie Damrau, Ph.D., Fellow

Applying Users’ Mental Models to Information Design

11

David J. Dick, Fellow

Tutorial Pacing

15

Viqui Dill

Hypergraphics for Visual-First Help: SVG, CSS, JavaScript 19 David Gardiner

Flipping Reports: Data for a Public Audience

27

Leah D. Hackleman-Good, Ph.D.

Optimizing Sound for E-Learning

33

Robert Hershenow

Using Scenarios to Help People Learn

37

Kim Lindsey

Let’s Get Real: Creating Tangible Products

39

Marli Mesibov

Stop Repeating Yourself! Use Video to Capture Knowledge 41 Matthew Pierce



iii



Delighting Mobile Customers with Content for Apps, Videos, and Social Media Campaigns

43

Marta Rauch, Associate Fellow, and Emily Hamer

Leadership and Management Becoming a New Manager

51

Todd DeLuca

Simple Scheduling

57

Mike Sawyer

Copyright Licensing for Review and Reuse

61

Dylan Tuttle

Tools and Technology Smoothing the Transition to DITA: Expert Partners Can Ease the Pain

67

Nicki L Davis, Ph.D., Associate Fellow

Can Lightweight Markup Punch above its Weight?

71

Raymond Gillespie

Git Started: Hands-On Git for Agile Writers

79

Sarah Kiniry

Iterative Development Models and Process Improvement

85

Tina M. Kister, PMP

EPUB: One Format for All Deliverables

93

Scott Prentice iv

2015 STC Technical Communication Summit Proceedings



Training and Research Effects of Electronic Media on Technical/Scientific Communication: A Look at the BP/Horizon Deepwater Oil Rig Explosion

99

Carolyn Boiarsky, Ph.D., Associate Fellow

Moving into Instructional Design

109

Stephen Van Esch

Writing and Communication Developing and Delivering Sample Projects as User Assistance 113 Nicky Bleiel

Clever Copy for Happy Users

115

Lauren T. G. Colton

How to Make Sense of Any Mess

121

Abby Covert

Performing a Global Audit

127

Leah Guren, Fellow

A Cross-Discipline Approach to Content Strategy

131

Denise Kadilak

Hardware Writing: You Can’t Always Touch It

135

Richard Lippincott, Associate Fellow

What I Know Versus Reality

141

Cindy Pao, Associate Fellow 2015 STC Technical Communication Summit Proceedings

v



Don’t Just Shrink It; Rethink It!

143

Marta Rauch, Associate Fellow, and Jennifer Stout

Getting Started in Policies and Procedures: Lessons Learned 149 Jamye Sagan

Technology and Tools in Policies and Procedures

153

Louise Tincher

API Documentation Survival Strategies: Building Your First Website for API Documentation 157 Mary Linderman and Andrei Essaoulov

Consulting and Small Business Management Winning the Project with an Effective Proposal

165

Alisa Bonsignore

Contract or Captive: Which Is Right for You?

167

Brenda Huettner, Fellow

vi

2015 STC Technical Communication Summit Proceedings



2015 STC Technical Communication Summit Proceedings

vii

ART, DESIGN, AND VISUAL COMMUNICATION BPMN Basics: What You Need to Know for Your Content Strategy

1

Jackie Damrau, Ph.D., Fellow

Applying Users’ Mental Models to Information Design

11

David J. Dick, Fellow

Tutorial Pacing

15

Viqui Dill

Hypergraphics for Visual-First Help: SVG, CSS, JavaScript

19

David Gardiner

Flipping Reports: Data for a Public Audience

27

Leah D. Hackleman-Good, Ph.D.

Optimizing Sound for E-Learning

33

Robert Hershenow

Using Scenarios to Help People Learn

37

Kim Lindsey

Let’s Get Real: Creating Tangible Products

39

Marli Mesibov

Stop Repeating Yourself! Use Video to Capture Knowledge

41

Matthew Pierce

Delighting Mobile Customers with Content for Apps, Videos, and Social Media Campaigns Marta Rauch, Associate Fellow, and Emily Hamer

43

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 processes 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 better than traditional words. This is a brief introduction into the world of process mapping that is different than standard flowcharting.

BPM Basics

B

usiness Process Management (BPM), according to Search CIO (http://searchcio.techtarget.com), is a “systematic approach to making an organization’s workflow more effective, more efficient and more capable of adapting to an ever-changing environment.” BPM encompasses using your technical communication skills to describe information in understandable terms for an audience. The output of describing information can be in any form, like business requirements or content strategy requirements. In those outputs, we place information into technical and non-technical terms so that the respective audiences understand the content being delivered.

A model is a graphical element (a visualization and data entry device) that conveys meaning, specifically the logic of activity flow from process start to process end. A process is a sequence of activities that maps the possible paths (as much as possible, not all paths can or should be modeled) with all its successful paths (“happy” path) or failures (“exception” path). Models help to reveal the order of activities, when the activities happen, and under what conditions the activities occur. A model does not describe how an

activity is performed or where or why it is performed. It barely touches on what the activity is or who performs it. The “who performs it” part is dependent on the model type you use. If you use a swimlane model, then knowing the ‘who performs it” is required. Otherwise, you can use a freeflow model where the “who performs it” is not identified. The activity flow is the most important part for assessing problem spots in the process itself. When preparing for modeling, you can use process logic to help you elicit the right amount of information so that you can construct the process model as well as using that same information to write the business or technical requirements document that the developers and quality assurance teams use when building and testing applications. As you begin modeling, you need to know if the process you are working on is a “current” (As-Is) or a “future” (To-Be) process. Modeling an As-Is process is often easier than a To-Be; yet it is possible to elicit enough information to build a To-Be process model. Modeling the processes requires meeting directly with the subject matter experts (SMEs) who are involved in the process (sometimes job shadowing the actual performers of the process helps as well in identifying issues of which the SMEs may not be 1

Art, Design, and Visual Communication

aware). During your SME meetings, you do not need to define every conceivable possibility. You should cover the basic “happy” path and major exception paths that prevent business from occurring (As-Is processes) or may prevent business from occurring (To-Be processes). During the process meetings with the SMEs, you might ask questions like: •

How does the process actually start? What activity triggers it? Is there more than one possible way it can start?

•

What determines when the process is complete? Are there different end states (success versus failure)?

•

How does the process go from Activity X to Activity Y? Does the person doing Activity Y somehow know when to do it?

•

How do you know when Activity X is done? Does Activity X always end in the same way? Are there any exceptions to how Activity X can end? Are there any specific business

rules in place to prevent or guide the next action state? These questions help you gather the information needed for building the process model. As you build the model, additional questions may arise as you begin analyzing the process and laying out the model. Supplemental SME meetings are useful in clarifying the process’s content as well as the accuracy and completeness of the business or technical requirements.

BPM Notation (BPMN) The Object Management Group (OMG) governs the Business Process Modeling and Notation (BPMN) standard. The current standard, BPMN v2.0, has been available since 3 January 2011. Visit http:// www.omg.org/spec/BPMN/2.0/ to read the full 538page specification standard. From the BPMN standard, OMG defines BPMN 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 processes, to the technical developers responsible for implementing the technology that will perform those processes, and finally, to the business people who will manage and monitor those processes. Thus, BPMN creates a standardized bridge for the gap between the business process design and process implementation” (p. 31). This paper covers the modeling notation with example models at a high-level. The BPMN objects can be overwhelming upon first glance. However, not all objects are used in one process. Figure 1 shows a poster image of the available BPMN objects. The BPM analyst should select the ones that are useful. In some cases, the company may select a subset 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 (Figure 2). Becoming familiar with the use of this notation isn’t as daunting as it looks. Several books and online education courses or certifications are available

for you to gain the knowledge needed in modeling and understanding the field of business process management. For some who have modeled in the past, the method in which you model for a workflow engine system or a Business Process Management Suite (BPMS) application may be different. This paper does not specifically cover how to model for a system or application. However, feel free to contact me or do your own research to discover the “correct” way of modeling if your process models will used by a workflow engine system or a BPMS application. Now that you have briefly seen the BPMN objects, let’s take a look at the various process model types that you can use in modeling your process content.

Process Model Types The types of process models that are available can vary depending on what you are trying to model. The ones listed here are just the few that I have exposure

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 below with a small description of the flow itself.

Simple A Simple process (Figure 3) has a Start and an End, contains at least one User task (Receive Order), may have a Service task (Check Credit), and may have a Subprocess task (Fulfill Order). A “Service Task” is one that the system performs with no human intervention. A “Subprocess Task” is one that you do not want to show in this model; it can be contained on a separate page or expanded later into the full model (see Figures 4 and 5).

Subprocesses (Separate Page) A Subprocess (Figure 4) has the same components as a Simple process, yet we introduce two new elements: a Decision Gateway (the diamond) that has a Yes/No path with two End path outcomes. Whenever

you have more than one Start or End object, you should label them accordingly so that anyone reading the process model can understand what the incoming and outgoing points are.

Subprocesses (Simple—Expanded View) A Subprocess (Simple – Expanded View) has the same Simple process components, yet the “Fulfill Order” subprocess is now expanded within the same process model (Figure 5). Note that the expanded Subprocess has its own Start and End notation and that the incoming connector stops at the beginning of the Subprocess object and the outgoing connector starts at the end of the Subprocess object.

Exception Path (Simple) An Exception Path (Figure 6) has the same Simple process components, yet it now includes two 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 have two Decision Gateways (diamonds) connected to each other. Each Decision should have an action (activity) that must occur before the next Decision kicks off.

Loopback A Loopback (Figure 7) starts to become a bit more complex than the Simple process. Now, we are beginning to show what happens when something doesn’t occur (“In stock?”) and the paths that must be taken to fulfill the request (“Offer Replacement Item” – “Accepted”) or cancel it (“Offer Replacement Item” – “Order failed”.)

Decision Gateways (Parallel Split and Join)

as AND, OR, or XOR operators to split paths. A split path can have more than one activity occurring at the same time (parallel) or the one path completes before the next path starts (sequential). (This brings back some algebra concepts that require thought.) Refer back to Figure 2 for the definitions to these operators. Whatever you do when modeling with these Decision Gateways, whatever object you use to split the path, you must use that same object to join the path. You cannot use an AND to split and an OR to join. The bottom portion of the Decision Gateway in Figure 8 shows two ways that the OMG standard approves of splitting paths. The first two are my personal preference for easier readability. I’ve found that business and technical people get less confused that way. However, you must make your own decision 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) A Simple Swimlane (Figure 9) process is the same as the Simple process. The complete model is the pool (Order Process) with the individual segments being the lanes (Sales, Finance, Warehouse). The main difference here is that we are now putting the activities performed by a job role/department or a system into its own lane. This makes reading the process flow easier to understand and to see potential bottlenecks when looking at resource capacity. (Note: Never use actual names in your models. Always use a job role (Accountant) or department (Finance).)

Swimlane Subprocess (Expanded) An Expanded Swimlane Subprocess (Figure 10) shows how you take the “Fulfill Order” subprocess and expand it within its specific lane.

Different Events, Activities, Data Elements, and Sequence Flows The Different Events, Activities, Data Elements, and Sequence Flows (Figure 11) process uses more of the BPMN objects from Figure 2 to show a complete model with artifacts (“Order”, “Customer Account”) hanging off of their respective objects. Some process modelers need this additional detail when reviewing with the business to make sure that the information is properly captured.

Reasons for Documenting BPM Processes Documenting processes is important for a business to know where the work is being done, where the bottlenecks in that work are occurring, and what actions need to be taken to resolve any potential 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 language and strengthen shared mental models on how to think about what they do and how to improve upon that work. Level-set workgroup members on the context of work they do (contributions to external customer value, part/whole workflow relationships, and contribution or relationship to the company’s primary workflow). Make work architecture visible for subsequent action to improve upon the work, define or pilot alternatives, and assign ongoing workflow ownership.

•

Improve communications and understanding within the workgroup.

•

Codify knowledge related to work.

•

Establish or make changes to the company’s process architecture (workflow).

•

Follow an established framework depending on the company’s industry (QMS, TQM, CMMI, Lean Six Sigma, Balanced Scorecard).

Software, Tools, and Repositories 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/ wikis to house all the information (knowledge). The days of tribal knowledge walking out the door through attrition or reductions in force is lessening. The items mentioned in this section are the ones that the author is most familiar with and have used. Many other options are available depending upon your company’s needs. Modeling Tools: For process modeling or concept map modeling, tools commonly used include simple ones like Microsoft Visio or Lucidchart (a cloudbased option) to complex application suites like ARIS Business Platform or Ultimus BPM Studio. Storage Repositories: The common storage repositories we hear of or are using include SharePoint, Documentum, and TFS. Many companies are moving away from SharePoint to TFS as they adopt the use of Agile in their requirements and development processes. Figure 12 shows a possible repository structure for consideration for your BPM projects. Email or Internal Social Media Outlets: Options available here include Yammer, Jive, Groupware

artifacts that are relevant to the project, article summaries, new procedures, and team skills. These resources are great for working with information, yet they still require workflow system interaction. Workflow system interaction is proven to provide companies with agility through the use of electronic systems to manage and monitor business processes. These electronic systems help in: •

Defining and tracking workflow between individuals

•

Moving information in document form based upon defined processes

•

Tracking the process of creating, reviewing, and distributing documents for action

Learning More About the BPM Profession As you enter into the BPM world, you need to understand the field itself. Figure 13 gives a list of 14 things that you need to feel comfortable in performing or have knowledge in when venturing into any project, 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: Degrees Kelley School of Business

•

BS, Business with an Information & Process Management Major

Widener University •

Certifications Boston University

•

bpmessentials.com

•

University Alliance

•

University of California – Irvine

•

University of Illinois – Springfield

•

University of North Carolina – Charlotte

•

University of San Francisco

•

Villanova University

Widener University

•

Association for Information and Image Management (AIIM)

•

Object Management Group (OMG)

Professional associations to consider joining or at least checking on are:

MS, Business Process Innovation

•

•

•

Association of Business Process Management Professionals (ABPMP)

•

International Institute of Business Analysis (IIBA)

•

BPM Institute.org

Conclusion BPM is an exciting field for those who have a desire to analyze and improve business processes. This paper’s goal was to show you how to model workflow concepts using BPMN when writing business and technical requirements that developers use in building 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 professionals can use these same concepts in determining how to structure content, especially when encountering writer’s block.

Resources “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

Author Biography Dr. Jackie Damrau is a Senior Business Systems Analyst with a leading commercial real estate company with more than 25 years of technical communication 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, philosophy, and business process management. Find her on LinkedIn (http://www.linkedin.com/in/jackiedamrau) 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

L

et us start with a high-level view of the concept of shopping in a store. I chose shopping because it combines several processes and has evolved from shopping in a store, to mail-order from a catalog, to shopping online. When consumers shop in a store, promotional items are placed at the entrance. If consumers know what they are looking for, they go

to that department (e.g., clothes, sporting goods, or household appliances). They compare prices of similar products sold at other stores. They might ask for advice or help from a sales clerk. Eventually, they buy something or leave the store with no purchases (see Figure 1). Additionally, they might return an item and ask for either a refund or an exchange. When consumers shop online, they expect a comparable 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 consumer 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.

Figure 2. User’s Mental Model of Shopping Online To design user assistance for shopping online requires an understanding of the questions and concerns consumers have about the online shopping process. Of course, it’s important to design the website to avoid a mismatch of the user’s mental model about shopping online and how the website is actually designed.

Why We Should Care About Users’ Mental Models Mental models are a key concept in the development of instructions, tutorials, demos, and other forms of user assistance. If we do not help users to develop accurate mental models of how products are designed, then we leave users on their own to develop their own mental models. If their mental models are not correct, users might have problems using the product, which makes for a frustrated user.

Practical Approaches to Understanding User’s Mental Models

•

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 much of their mental model.

Methods to Help Users Develop Accurate Mental Models 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 various learning styles; however, you need to offer multiple methods in which users can build accurate mental models of the program. •

Marketing Brochures. A marketing brochure answers questions about the product in a logical sequence following the reader’s train of thought. The best way to start is by analyzing what users want to know, and then assess the order in which their questions will flow. A good way to organize your points is to write down the questions you think a potential reader might have and the answers your brochure might supply.

•

User Guides. For user guides to be useful, they need to need to be written for various readers, ranging from those with little or no experience with the product to those with significant experience with the product (or similar products). The ideal user guide identifies the important high- and low-level processes that allow the reader to develop an accurate and useful understanding of the product.

•

Quick Reference Cards. Few people want to read a book cover-to-cover when they only want to learn how to perform a few key tasks. A quick reference card gives an overview of the program and instructions on

There are several practical approaches to learning about the user’s mental models. •

•

12

Sketching. In the early stages of design, invite users to explain their understanding of every visual element of the product. If their explanation does not match the design or the design does not match their understanding, then you have identified possible problems that should be corrected in a redesign. Card Sorting. Card sorting is a reliable and inexpensive method for finding patterns in how users would expect to find content or

2015 STC Technical Communication Summit Proceedings



Applying Users’ Mental Models to Information Design

how to perform a few key tasks (e.g., create, edit, delete). The user can always refer to the manual to learn more detailed information. Quick reference cards are an ideal takeaway from any kind of training course. •

•

Help. You are likely to find Help in most programs and browser-based applications. For Help to be useful, it should allow users to search topics for individual tasks, as well as for patterns between common tasks. Instructional Videos. If users do not like reading user guides, the next best thing is instructional videos, which help to reinforce concepts about how things work in a visual and memorable way. Instructional videos are typically available from vendor sites and YouTube.

Author Contact Information David J. Dick Fairfax, Virginia [email protected]

Author Biography David Dick is an STC Fellow, member of the Washington, DC–Baltimore Chapter, and manager of the Usability and User Experience Special Interest Group. David is co-author of Web Services, Service-Oriented Architectures, and Cloud Computing: The Savvy Manager’s Guide. You can follow his musing about usability at http://notebook.stc.org/tag/david-dick/.

Summary 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

Resources 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

TUTORIAL PACING Viqui Dill 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”.

S

o you’re about to make a new tutorial for an audience of folks who want to learn how to use a brand new system.

If you’re like me, you may never get to meet the actual users. My company makes kitchen cabinets, which you can buy online. It’s really hard to buy a whole kitchen worth of cabinets and if you make a mistake, it’s usually a very costly and sometimes embarrassing mistake. My users are kitchen designers who take the home owner’s input and measurements and turn the home owner’s dream into a design and a list of parts to order for the kitchen. They will need to order everything from the cabinets themselves on down to the decorative handles and functional accessories like the wine rack and slide out trash bin. I always assume that any user who is desperate enough to go to the online help is 3 things: •

New—they are new at the system and they want reassurance that it will be worth their time to use it.

•

Alone—they are working alone at the moment, otherwise they would have just asked a coworker the question.

•

Bothered—they are either angry, or scared, or both.

no matter what the task is, they can do it if they just hang in with me and follow my instructions. OK, so that’s who will do the learning and the watching and listening. Since these folks don’t work for my company, I have no prayer of ever meeting them. Who will I be working with while I’m creating the tutorial? Who will tell me what’s involved in each process? Who will give the final approval when I’m done? I will be working with the MIS folks who have designed the system for the designers to use. These guys and gals already know how to use the system. They will already know how to do each task. They will already know the answer to every question. They will be more concerned with accuracy and completeness of the content than with the effectiveness of the delivery. They will have very little patience for watching the tutorials teach them what they already know. So I have to be able to build a bridge from what the SMEs, Developers, and maybe even the Marketing folks tell me to the actual needs of the actual users of the system.

Too Fast or Too Slow 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

15

Art, Design, and Visual Communication

How fast is too Fast?

o Match video

New folks need

o Read along

•

Time to see

•

Time to read & hear

•

Time to reflect

•

Time to interact

§ 0.5 seconds after caption

•

To know what’s next

§ 1.0 second after screen change

o Step by step o Pauses match video

Well-paced material is “sticky”

How Slow is too Slow?

§ 2.0 seconds for transition to next screen

•

o Explain concepts

Bored learners will •

Click off

•

Multitask

•

Not come back

Narration

o Anticipate a question o Overview or summarize o Pauses match content

Well-paced material is engaging

§ 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 and audio pacing.

§ 3.0 seconds for reflection

Visual Pacing

Audio elements as objects Silence separates phrases, sentences, ideas

Visual tracking vs. visual focus •

Tracking o 1.5 second mouse sweep o 1.0 second silence o Highlight box

•

Focus o Highlight box or draw ovals o Show mouse click 0.5 seconds

Audio Pacing Instruction vs. narration • 16

Instruction

Figure 1. Audio sample Audio Energy Too much vs. too little

•

High energy o Stimulating o Dynamic

2015 STC Technical Communication Summit Proceedings



Tutorial Pacing o Driven

•

Low energy o Calming o Confident o Contagious

•

Time to reflect

•

Change to next slide

Other Ways to Improve Engagement Interact •

Skip intro option

Putting It All Together

•

Clickable pacing

Combined pacing of audio and video:

•

Roll over text

•

Roll over graphics

•

Review

•

Change slide

•

Show what & where

•

Tell with voiceover

•

Focus visually

•

Show what & where

What’s Next? Interactions Last slide offers choices •

Review old tutorials

•

Move ahead to new tutorials

•

Email me

•

Online Help links

•

Links to external sites

Summary Summary of conclusions: •

Design for audience

•

Engaged students need o See/hear/touch

Figure 2. Combined pacing of audio and video

o Time to reflect o To know what’s next

•

Well-paced material is “sticky”

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 education 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 follow 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 FOR VISUAL-FIRST HELP: SVG, CSS, JAVASCRIPT David Gardiner Hypergraphics is an emerging area of visual communication that uses HTML5 technologies. 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, mobilefirst documents. Applications include visual-first web app documents, multilingual graphics 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

T

he increasing need to deliver online documentation, the challenges in adapting content for mobile devices, and the demand for more interactive user experiences can be met with hypergraphics (hyperlinked infographics). The HTML5 technology of scalable vector graphics (SVG), together with CSS3 and JavaScript, can produce interactive illustrations as a visual alternative to text content. SVG-based hypergraphics can be integrated into existing online documentation workflows, and websavvy technical communicators will adapt quickly to this XML format because of similar functionality to HTML. Standard technical illustration and graphic design software can output the graphics format for display in desktop and mobile browsers. Potential benefits for developing new visual interfaces and reuse of graphics for translation make SVG hypergraphics a versatile enabling technology for “visual-first” online help. There are instances where authoring concept, task and reference topics might be better visualized as hypergraphics, so that users would tap on a visualization of a product or service to find information. Individual parts of graphics in

SVG format—lines, shapes, text—can be hyperlinked. So anything you can draw, you can turn into a hyperlink to navigate documentation. A number of trends in technical communication technologies and processes are seen as integrating with and supporting SVG hypergraphics. HTML5 is now the web standard for presenting help content, and SVG is a new HTML element that is a vector format for illustrations which can be displayed in all major browsers. Cascading style sheets (CSS3), and in particular media queries, work with SVG hypergraphics to change the display of graphics when adapting content for desktop and mobile devices. Some aspects of responsive web design can be applied to SVG interfaces, such as resizing graphics to fit browser width. Designing infographics and visuals to support text-based procedures is becoming more prominent in technical documentation, and interactive SVG infographics are used in other disciplines for representing statistical data. Video is one such visual tool that is booming, and with some limitations, videos can be embedded in SVG illustrations and played in browsers. Mobile-first production 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 incorporating design considerations of all these tools for delivering content, which ultimately enhances the user experience.

HTML5 Standards Scalable vector graphics is an XML-based format for displaying graphics in PDF and browsers. SVG is a text-based format much like HTML5 and shares many similarities in markup, such as hyperlinking. The format is capable of enhancing vector graphics (e.g. illustrations) with interactivity, animation and filters (e.g. drop shadows and highlights). SVG has in fact had a long history, having first become a W3C recommendation in 1999. However, it has been a “sleeper” technology until 2011, with very little development of potential applications. It’s taken all this time for SVG to gain acceptance, mainly because web browsers only gradually implemented different functions of the SVG specification. At first, no browser could display SVG—it was for print documents only. Gradually, browser developers began to support the format—Google Chrome, Firefox, Opera, Safari and eventually Internet Explorer. Finally, with the release of the Android 4.0 operating system for tablets in 2011, all desktop, mobile and smartphone browsers can display SVG. Cascading style sheets (CSS3), and particularly media queries, are compatible with SVG. This allows user feedback for “mouse over” events to indicate that a graphic element is hyperlinked. Either external or internal style sheets can be added to an SVG file, class names added to each graphic in SVG, and class attributes specified so that a graphic changes color and line width increases when a user hovers the cursor over different parts of a graphic. For the most part, SVG uses the same CSS attributes as HTML5. There are variations—such as “fill” instead

Figure 1. SVG markup showing similarities with HTML and CSS elements. 20

of “background-color”, and “stroke” instead of “border-color”—which achieve similar visual styling for hypergraphics as standard CSS achieves for hypertext (Figure 1). Responsive web design uses CSS3 media queries to modify web content for mobile devices (Perlin 2014). By specifying different browser widths using breakpoints, or changing the orientation of the device (for example, tablets used in portrait or landscape format), graphics can show only the most relevant information for smaller screens on mobile devices. Interactivity on mobile devices requires JavaScript and jQuery to enable touch gestures such as pan (swipe), zoom (pinch) and tap (touch). There are a number of JavaScript frameworks and libraries that can be implemented with SVG to add an interactive experience that is expected when using mobile devices. Frameworks such as snap.svg, interact, Hammer.js and D3 offer various functionality for touch gestures. Technical communicators with a reasonable grasp of coding in general can implement such open-source JavaScript frameworks with SVG and HTML5 with a minimal amount of JavaScript that needs to be hand-coded.

Building the Case for Hypergraphics Opsteegh (2013:7), in the context of visualizing data, says that infographics can persuade the audience, and that readers tend to rely on information conveyed by infographics rather than any accompanying text. So making the connections between these technologies and user expectations leads to an inevitable need for hypergraphics that enable visual-first and mobile-first documents. Technical communication practice is still wedded to the idea that infographics are static representations of concepts or processes that technical documentation 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 concepts of “technical comics” and data visualization using infographics—which focuses almost exclusively on portraying statistical information such as for dashboard reports; such examples of infographics 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 with. But now we need to create content for mobile 2015 STC Technical Communication Summit Proceedings



Hypergraphics for Visual-First Help: SVG, CSS, JavaScript

devices. There is now a timely convergence of web technologies, as well as demand for mobile documentation, that forces a rethink about how documents need to be presented to users who expect interactivity and highly visual interfaces. Replacing written concepts and tasks with hyperlinked infographics, or hypergraphics, has considerable potential to improve the user experience because these act as shortcuts to understanding concepts, carrying out tasks, and finding reference information quickly (Figure 2). Hypergraphics can potentially enable documentation—presently structured as conventional, linear, book-like text—to be fragmented into very small topics yet still accessible using graphics as the interface for finding information. It also opens up technical communication to best practices in Web and mobile design, because succinct visuals linked to small topics convey more meaning and grab the attention of users who now expect an interactive experience akin to using smartphones. Users expect fast learning and quick answers, so presenting small and disparate web topics that are linked through visuals can begin to satisfy those

needs. The idea of sketching documentation might also come more easily to new technical communicators used to a world of visual information—the thought of learning how to write all documentation may seem archaic.

Challenges in Mobile Documentation Cooper and Rockley (2014), in presenting trends in mobile documentation, intimated that “We need an alternative way to display tables on mobile devices.” Responsive data tables formatted with HTML elements have been proposed using CSS or JavaScript solutions (Coyier 2012), where for example data is presented as a long and narrow table, or by conditionally hiding less important columns. The issue of displaying tabular data for online help became apparent to me in the early stages of writing web documentation for an ebook publishing product. It was not until I conceptualized an interactive interface, and later tested the information design on an Android tablet, that I realized SVG has the potential to solve the problem of formatting reference 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 documents, reference information has been formatted as tables. However, this way of showing information no longer works well for mobile devices.

up: the front cover, imprint page, table of contents, chapter title page, bibliography styles, and so on. Once I exported each graphic to SVG, I applied 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 “mouse over” events).

Potential Applications

Later I wrote DITA concept topics to design an information structure for background concepts and hypertext links to each hypergraphics page. Each page of the resulting WebHelp documentation contains concept information, and has an icon linking to a hypergraphics page which contains infographics that link to reference information in standalone web topics. So, rather than having reference topics formatted as tables in the documentation (and accessed, for example, by clicking on a link in the WebHelp tripane’s table of contents), they are standalone web topics accessed by clicking on infographics that rep-

The challenges in adapting content for mobile devices—the barriers posed by text-intensive book-like documentation that is difficult for users to navigate, and presenting tabular data on small screens—can start to be overcome by reformatting content using visual interfaces. Conceptualizing and drawing hypergraphics is a cost in the time taken, so there must be a benefit to make them a feasible part of the document production workflow. Apart from creating a more engaging user experience that shows only relevant task-based information, hypergraphics can fill gaps in delivering content on mobile and 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 reference 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. The reference information had to have a visual interface, so that users could see in a browser the different components of a book: the end product of using the style sheets. I also envisioned the end result of using the product—a book, and pages of a book—and had the idea of creating interactive graphics that users could tap on to find reference information. The intended audience was book editors and publishers, so I was already familiar with how those users would like to access reference information. To have documentation that visually represents the end result of using the software would quickly orientate users with the features of the product and familiarize them without too much reading. I started drawing various pages of a book in Adobe Illustrator to represent styles that users would set 22

Figure 3. Reference information in a hyperlinked web topic. resent the reference information (Figure 3). This information architecture is broadly consistent with the concept of “Every Page is Page One” topics, which exist outside of a book-like structure, have no parent topic, and rely on linking to establish their own context (Baker 2013:140).

Translation/localization SVG markup works with browser functionality in being able to display multilingual text in a browser. During document production, a translator can add translated text into an SVG file using a text editor, and special coding in the markup specifies the language of each piece of text. As the end result, when 2015 STC Technical Communication Summit Proceedings



Hypergraphics for Visual-First Help: SVG, CSS, JavaScript

a user viewing the graphics sets their preferred language in browser preferences, the browser interprets this coding and switches languages.

using a service. Or there could be an illustration with a video embedded which engages users as an e-learning tool.

In a way, this is “single-sourcing” graphics in that a technical communicator draws infographics once, and adds multilingual text to enable reuse of the visual content depending on how a user chooses to view it (in this case, in the user’s native language). It means there is no need to create multiple images for each language when producing graphics, because one graphic contains all translations and browser settings determine what language is displayed.

The advantage of visual-first interfaces is that technical communicators can sketch explanatory concepts and procedures designed for interactivity—anything you can draw, you can hyperlink with SVG. Users see the product or service they are using to quickly become familiar with it, and get touch gestures that they would expect when using a mobile device.

Visual-first, Mobile-first Documents Graphics should be the first thing that a user interacts with in documentation (such as a quick-start guide), such as an illustration of the product or service with links to concepts and procedures. In this way, hypergraphics can restructure documentation to have visual-first interfaces that quickly orientate the user. A graphic could be a diagram of the product with interactive hotspots that link to web pages on key features. Or it could be a process flowchart that represents the steps a user needs to go through when

A clear application of visual-first interfaces is for quick-start guides. For example, an online help document for a washing machine would contain exhaustive details about safety information, various settings and procedures for different wash cycles, preparing clothes for washing, and specifications for the machine. A new user simply wants to do their first wash to get a feel for the product and not be overwhelmed by reading all the information, most of which might be irrelevant for their needs. The first page in online documentation could have interactive icons and diagrams of the washing machine with hyperlinks to small parts of the document that have key information to get started quickly. Numbered 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 approach means users don’t need to understand how to first navigate the document structure or be inundated with superfluous detail.

Integrating Hypergraphics into Workflows Hypergraphics using SVG can be integrated into existing document production workflows that produce online help. Wherever online documents are produced using HTML, then SVG can similarly be used for visual interfaces. Because there is no one graphics package that can handle all types of interactivity as demonstrated in this paper, a toolchain of software packages is required to: progress from initial design or sketching; export SVG; clean up the coding; add hyperlinking to graphical elements; incorporate JavaScript functions and link to jQuery frameworks; and test the output in browsers. A reasonable amount of hand-coding is required along the way, because producing or modifying hypergraphics cannot be done entirely by WYSIWYG editors currently available. Some hand-coding is inevitable when inserting translated text for example. Technical communicators can use standard illustration software packages such as Adobe Illustrator or CorelDRAW to sketch graphics then export them as SVG. These commercial tools produce “clean” SVG markup with external or internal CSS styles. Other commercial graphic design tools claim that they are SVG editors, but one limitation is that when exporting SVG, “inline” CSS styles are generated for every graphic element—not only does this create problems when trying to change class styles using CSS (such as :hover color or line thickness) for a number of graphical elements, but also there are redundant elements that must be deleted to allow for easier editing of line and shape styles. While there are also specialized open-source SVG editors, such as Inkscape, these also suffer from extraneous markup such as namespace declarations and prefixes. The disadvantage is that hypergraphics created and styled in one graphics tool might not be easily edited in another. For SVG that has inline CSS styles and redundant coding, it is recommended to clean the file using an online tool SVGOptimiser. This removes namespace declarations and superfluous inline style attributes, to produce a smaller file that is easier to edit later. 24

Adding hyperlinks to graphics can be done with WYSIWYG design tools such as CorelDRAW before exporting to SVG, although this can produce multiple xlink:href attributes for each graphical element that comprises an infographic, whereas ideally you only need one hyperlink for each infographic (comprising of multiple lines and shapes). Because SVG is text-based, then a text editor such as Notepad++ or an XML editor can be used to add hyperlinks to infographics. For sophisticated applications such as multilingual graphics as demonstrated in this paper, an XML editor or text editor is required to add valid SVG markup. Also, JavaScript is essential to achieve more complex interactivity that uses browser functionality. Fortunately, only minor hand-coding is required to implement JavaScript frameworks that support touch gestures.

Conclusion Hypergraphics combines the principles of web design and information design. Extending the concept to where the design process restructures written documentation into fragmented and modularized visual-first interfaces means also including aspects of infographic design applied to user assistance. SVG represents a timely convergence of technologies to help design visual document interfaces with minimal outlay on production tools. A few technical communicators are already using interactive SVG for applications such as aircraft parts catalogues and animating step-by-step procedures showing how to use products. By producing web documents, we already have many of the skills in markup languages to start creating hypergraphics. We can apply our skills in designing documents for structure, hyperlinking and styling to improve the user experience, and start creating value-added documentation with this highly accessible graphics format.

Resources Cop-e-boox™ style sheets. http://sourceforge.net/ projects/copebooxstylesheets/ Gardiner, David. “Interactive Hypergraphics Design.” Communicator (Winter 2014): 21-24. Gardiner, David. “Visualising Online Help Topics.” Communicator (Spring 2015): 38-41.

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 firstlevel certificate in technical communication. Broad experience in graphic design for print and web includes digital mapping, preparing communications materials, website writing and design, and flowcharting 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.

S

ometimes “technical” writing includes public documents that sit on the edge of advocacy: not quite academic reports, not quite marketing materials.

What to do? 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 indicators 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 The client did not want the report to look like a marketing brochure, but they were disheartened that no one actually seemed to read the report. After the time and effort to research and write about the important poverty statistics in our state, it’s frustrating that readers tended to use the report more like they would use an online resource, looking for the single piece of information they wanted and not attending to the rest. OACAA also realized that visual communications work better with a public audience, but staff did not want too “slick” a presentation. Also, the report had to be issued as a Word document so that partners and other local Community Action organizations could copy and paste the data.

Decisions and directions The structure the report usually followed: 1. Introduction 2. Defining poverty 3. Ohio poverty profile 4. Poverty and the recession 5. Community Action and economic recovery 6. Final thoughts 7. Bibliography 8. Data appendix

28

Figure 2. Process versus structure I proposed: 1. Opening letter 2. Seven important poverty subjects with graphics 3. Appendix with all data and notes

Challenges and tensions •

Keeping the word count low

•

Keeping the images visually simple

•

Integrating “stories” the client wanted within the new report

What worked? 1. Being involved immediately with the final client 2. Providing research to back up the proposal o Words versus images (and types of images) o Cognitive load of most adult readers

3. Visual simplicity based on structured writing principles 4. Organizational simplicity for the audiences’ needs

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

“Cmap Tools.” Florida Institute for Human & Machine Cognition. http://www.ihmc.us/ cmaptools.php

Results Notice by news outlets increased for the 2012 report (that is, regarding the report as a whole rather than simply using the report for numbers they need) compared to the prior year.

Evergreen, Stephanie. Presenting Data Effectively: Communicating Your Findings for Maximum Impact (Thousand Oaks, CA: Sage), 2013. Horn, Robert E. Participant’s Manual for Strategies for Developing High-Performance Documentation (Waltham, MA: Information Mapping, Inc.), 1996.

Other Applications Sometimes a client will not accept a full-on visual display. But because they understand the importance of visual communication in the era of online access, we can encourage other clients to implement flipping in another way. For example, in reports for three different clients, I have developed a one-page “chapter opener” that draws attention to the most important (as determined by the client based on its mission and the purpose of the report) data in that chapter.

Ohio Association of Community Action Agencies. State of Poverty 2012 (Columbus, OH: OACAA), 2012. http://www.oacaa.org/ wp-content/uploads/2013/01/State_of_ Poverty_2012_Final.pdf National Cancer Institute. Making Data Talk: A Workbook (Washington, DC: National Institutes of Health, US Department of Health and Human Services), September 2011. Ware, Colin. Information Visualization: Perception for Design (Amsterdam, Netherlands: Morgan

References and Resources Alley, Michael. The Craft of Scientific Presentations, 2nd ed. (New York, NY: Springer), 2013. Bateman, Scott, Regan L. Mandryk, Carl Gutwin, Aaron Genest, David McDine, and Christopher Brooks. “Useful Junk? The Effects of Visual Embellishment on Comprehension and Memorability of Charts.” CHI 2010, April 10–15, 2010, Atlanta, Georgia.

Acknowledgments Thanks to Community Research Partners, especially Director of Research Yvonne Olivares, who was 100% in favor of fewer words and more impact and who now owns Services for Data-Driven Solutions (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 displays 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.

A

good soundtrack won’t save a bad presentation, but bad sound can quickly ruin a good one. And it doesn’t take much to make it “bad” – even slight noise or distortion can distract and alienate an online listener. The good news is that, with a bit of knowledge and practice, it’s relatively easy to record and produce an effective soundtrack.

Microphones “How do I pick the best microphone?” Start with the five W’s (and an H): Who will use the microphone? If the answer is “just one person,” then a headset might be perfect… but if several people will share it, a headset may not be so attractive. What will you use the microphone for? Simply recording narration? Or will you also want to perform with it, or record guitar or environmental sounds? When and Where will you use it? As a fixed installation on a desk at work? Or will you need to move it around? Perhaps you’ll want something pocket-sized for remote work? Why will you record? To produce Captivate soundtracks? CDs or DVDs? You’ll want a better microphone (or perhaps even a hired recording studio) for a higher-fidelity release.



How will you record? With a computer program? If so, a USB microphone (that plugs directly into a computer and requires no additional parts) is most convenient. If you anticipate recording in the field, a portable digital recorder is worth considering. See “Resources” for more information about selecting and buying a microphone.

Software Many excellent recording and editing software programs are free, and many others offer free trials before you buy. Here are two excellent programs: Audacity is a free, open-source recording and editing program that runs on multiple platforms. It’s basically quite simple but advanced features are available as well, so – depending on which effects and add-ins you employ – you can work out your own level of complication. The program has an excellent online manual and a responsive user forum if you need help. Available from http://sourceforge. net/projects/audacity/ Garageband is Apple’s recording/editing software for the Mac and iOS, and as with most of Apple’s offerings it’s very easy to use. One popular feature is a selection of presets for voice recording, to quickly and easily add ambience to your narrative tracks. Available from the App Store.

33

Art, Design, and Visual Communication

Portable Recorders Portable recorders from companies like TASCAM and Zoom offer convenience, ease of use, silent operation, and very good sound. Some models even feature Wi-Fi connectivity for remote control, wireless transfer and streaming. They can run on batteries, they record to microSD media, and fit in a pocket or bag. They are great solutions for recording interviews and capturing sound in the field, and their cost is comparable to that of a good microphone.

and try to finish, it will be very hard to make the second recording sound just like the first. 5. Don’t touch the microphone!

Editing Tips 1. Save the original recording. Make a copy and edit that. 2. If you save incrementally, you won’t have to go back to the beginning if you need to rework a step.

Your phone or tablet can also be a high-quality recording device, with the addition of a microphone or digital interface. Several companies offer microphones and interfaces designed for iOS, Android, and Mac/PC devices.

3. Process the entire recording (or big pieces of it) before dividing it into smaller chunks. Also, document your processes so you can duplicate them.

Technique

4. Go easy on the EQ. Cut rather than boost. If it sounds thin, try cutting the treble instead of adding bass.

1. The qualities of the room in which you record will affect the overall sound of the recording. Experiment until you find a room – or a corner of a room – that sounds good, and record there. Be conscious of external noises that might contaminate the recording. Both room characteristics and external noise can be lessened by placing the microphone closer to the source (i.e., your voice) and speaking louder, which will allow you to decrease the record volume. 2. You can also shield yourself and the microphone from noise and room characteristics by setting up a vocal booth, which can be as simple as a blanket draped over your head and the microphone. Walk-in closets can make good vocal booths, as well.

Recording Tips

6. Use fade-ins and fade-outs for smooth transitions; don’t just chop.

Resources B&H Phot Video: Buying Guide – http://www. bhphotovideo.com/explora/audio/ buying-guides/voice-over-equipment Sweetwater Sound: Buying Guides – Studio Mics http://www.sweetwater.com/insync/ studio-microphone-buying-guide/ USB Mics http://www.sweetwater.com/insync/ usb-microphone-buying-guide-2/ Headphones http://www.sweetwater.com/insync/ headphones-buying-guide/ 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 speaking, count to five before you stop the recorder.

IK Multimedia: Mobile Recording Accessories – http://www.ikmultimedia.com/products/ cat-view.php?C=mobile

2. Record ten seconds of your first take, then play it back to make sure everything is working.

References

3. Save the first take. It’s usually the best, even if it doesn’t seem to be at the time. 4. Do it all at once, if you can. Read your entire script. If you come back a day or two later 34

5. Leave some room at the beginning and end of each phrase for a more natural sound.

Schroeder, Carla. The Book of Audacity. (San Francisco, CA: No Starch Press), 2011. Rothermich, Edgar. Garageband 11: How it Works. (Self-Published) http://dingdingmusic.com/ DingDing/GB11.html 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/15tips-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 equipment 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.

T

hought leaders in the training industry and marketing gurus are aligning with current neuroscience research that describes how our brains are “wired for story.” Learning retention increases significantly when information is presented in a narrative context.

In scenario-based instructional design, learners are placed into a story where the outcome - the consequences - are dependent on the choices they make. The story may be long and involved or extremely short, but always enables people to learn from their mistakes in a virtual, risk-free environment.

Jimenez, Ray. Story-based eLearning Design Workshop. http://www.vignetteslearning. com/vignettes/sbworkshop12.php.

References Kapp, Karl M. “Abstract of Study Related to Storytelling.” Kapp Notes (23 December 2014). http://karlkapp.com/ abstracts-of-study-related-to-storytelling/. Heath, Chip, and Dan Heath. Made to Stick: Why 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 Cinécraft Productions Inc. scenarios have a main character of some kind, in 2515 Franklin Boulevard some cases the learner themself is the only character. Cleveland OH 44113 +1.216.781.2300 The scenario format is thus adaptable to a broad 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

Resources Moore, Cathy. Scenario design: In-depth and hands-on. http://blog.cathy-moore.com/ scenario-design-online-course/.

Ohio. She is a Senior Member of STC and has held numerous offices in the Northeast Ohio STC chapter, including President; she is currently the chapter’s Webmaster. Kim has completed several certificate courses on scenario-based design from industry 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 producing 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.

W

hen I was twelve, it began to bother me that my friends were all immensely talented, creative, crafty, and artistic, and I was not. Many twelve-yearolds suffer from insecurities of this sort. What makes my situation interesting is that I was an excellent athlete, and what upset me was seeing my friends – mostly artists – creating beautiful, tangible, and often useful things, while my talents seemed more ethereal, and therefore somehow less real. Today, as a content strategist, I feel similarly drawn toward tangible deliverables: the things we leave behind with our clients.

When Does Lean Become Deliverable-Free? In 2011, Jeff Gothelf and Josh Seiden wrote a book, entitled Lean UX. Published by O’Reilly Media, the book served as both treatise and how-to, and it successfully revolutionized how many teams approached user experience. Their goal was to focus on experience rather than deliverables. The problem Jeff and Josh were solving for was a significant on: “[UX designers are] measured and compensated for the depth and breadth of their deliverables instead of the quality and success of the experiences they design.” With this in mind, Lean UX became a proponent of no deliverables. However, for content strategists and

UX designers – often considered “consultants” – this lack of deliverables can be met with a lack of respect. Worse still, no deliverables means that information gathered (via user research, discovery sessions, or collaborative workshops) lives within the minds of specific team members. Given that the average American employee changes jobs roughly every four years, we need a new plan – one that ensures teams won’t lose content and context when members move on.

Sensible Deliverables Just a year ago, Jeff Gothelf published a response to the many teams who have merely removed deliverables from their process. “Lean UX is not Antideliverables,” he explained. “Reducing deliverables is only one relatively small benefit of shifting our mindset away from traditional UX practices and thinking ‘lean.’” The key is to create (a reduced number of) deliverables that enhance and guide the experience. Jeff and Josh identified that many UX designers struggle with the perception that they merely create “designs.” So the first step to identifying a sensible, lean deliverable is to move away from the final product. The second step is to ask: what would the client need, if I were to leave tomorrow? It sounds dramatic, but ultimately, our goal for every project is to leave an intuitive, delightful, profitable experience without 39

Art, Design, and Visual Communication

the need for us to oversee it. With this in mind, a number of valuable deliverables come into play for visual designers, interaction designers, and content strategists alike, including: •

Style guide and brand guides

•

Interaction libraries

•

Conversational guidelines

•

Governance workflows

•

Checklists and prioritization questionnaires

•

Content audits

•

User journeys

•

User needs and business objectives

•

Analytics and measurement goals

Think Forward When Lean UX first came into being, deliverables 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.

http://www.uxbooth.com/articles/ research-right-audience/

Author Contact Information Marli Mesibov Director of Content Strategy Mad*Pow [email protected]

Author Biography

Marli Mesibov is the Director of Content Strategy at the design and UX agency Mad*Pow. Her work spans strategy and experiences across websites, web applications, and mobile for enterprise companies 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 on UX Design, content strategy, and Muppets. You can learn more about her and her work at http:// marli.us

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/leanux-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-ofcontent-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 knowledge 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

V

irgin Media was faced with an interest challenge: 150 employees were retiring and taking with them critical knowledge. Given the timeline and opportunity, the team working to solve the problem couldn’t just rely on Subject Matter Experts (SMEs) to write down the knowledge. They wanted to provide more context, more information, and make the tasks as easy as possible for the SMEs to capture the knowledge.

Casson McRae, a Learning Technology Designer at Virgin Media, took this challenge to heart. “A lot of what we do in the learning technology team is to explore and try out new tools. By using these tools, [employees] are developing new behaviors that are key for organizations in the 21st century.” Casson and team knew that it would take a lot to get information 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.

About using video Casson said, “What can be conveyed in a three minute video is so much information that we can’t convey by writing it down. Video allows us to capture and share tacit knowledge. The knowledge that is in the head of a lot of our people who are very experienced at what they do.” Especially in a company as large as Virgin Media, Casson points out how tutorial videos of various tasks and software can be reused across the company: “That one piece of content which was created to serve an individual’s need can actually serve hundreds or potentially thousands of people within an organization very quickly and just by being created once by an expert user.” In light of the success with their retiring workforce knowledge Virgin Media has rolled out the idea more broadly. They have scaled their program from the original 150 to approximately 15,000 of their employees.

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 • ­Provide high stake feedback, that needs to sites and hear the real challenges they are facing, include the tone of message to reduce confuemployees who go on visit are asked to report back sion, and can be reviewed as needed by the their experiences. These often would be shared in receiver. the all-company meeting on Monday mornings or 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 Turner, Kelly “Virgin Media: Recording employee but allowed him to share his experiences and findknowledge” TechSmith Blog (7.10.2014). ings while they were still fresh in his mind, often http://blogs.techsmith.com/customerjust minutes after completing a visit. Because the stories/virgin-media-recording-employeethoughts were recorded, anyone who wanted the knowledge/. information could access it as needed it, and have the benefit of clarity of listening to Troy convey “Empowering Colleagues to Share Knowledge cleary tone. Companywide” TechSmith.com. https:// www.techsmith.com/customer-storiesTechSmith technical support also uses video frevirgin-media.html. quently as they try to help customers solve technical issues. Once the team has identified an issue that Author Contact Information is beginning to develop a recurring frequency in 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 Author Biography item menus with name similarity.”

Potential Opportunities Both Virgin Media and TechSmith showcase a few examples of how video and images can help you from having to repeat yourself. Below are a few other ideas that organizations might want to employ to help save time and effort in their communications:

42

•

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 frequency or for items that are easily forgotten

Matt Pierce works for TechSmith Corp., a software company that provides practical business and academic solutions that change how people communicate and collaborate across devices. Matt currently leads the Social Media, PR, and Customer Stories team. Prior to working in marketing, Matt managed training, technical support, and has been an instructional designer. He is a regular contributed to several online publications in the U.S. and UK. 

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.

T

o delight mobile customers, provide useful content for mobile apps, develop mobile videos, and roll out social media campaigns. Here are tips and strategies for leveraging your content across multiple channels, measuring the benefits, and communicating the results.

We share these best practices for adding value and enhancing customer experience on your mobile products: •

Provide adaptive content

•

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

•

Communicate wins

Provide Mobile-friendly, Adaptive Content Ensure that your content is mobile friendly. As you see here, mobile app content includes: •

All text on mobile screens

•

Hints and tips on screens and in fields

•

Messages

Many apps include a mobile in-product tour. These tours help users: •

Learn key tasks while without leaving the app

•

Many mobile apps link to a library of content, FAQs, and other resources. Ensure that your library and its contents are mobile-friendly. As you develop content, check the library and your content on the devices that your target customers use. Install the app on a mobile device, and then test the link to the library from the mobile app. Design the library and its contents with mobile in mind. Content should look great on desktops, laptops, and mobile devices. For a quick test in a desktop browser, resize the browser page to the size of the mobile device. Content should respond to: •

Computer or mobile device

Quickly get up to speed on mobile features

•

Screen size

•

Finish the tour when they want, and come back to review content anytime

•

Operating system

•

Portrait and landscape mode

•

Save time and money by leveraging your mobile content across multiple channels:

•

App store descriptions

•

Content embedded in the app

•

Video scripts and captions

•

Mobile library best practices: •

Responsive design, for example, through HTML5 and CSS3

•

Easy to read on desktop, laptop, and mobile devices

YouTube video, channel descriptions

•

Tested on mobile devices

•

Social media campaigns and posts

•

Links to mobile videos

•

Blogs and marketing communications

•

Mobile-friendly library

Strategic considerations when developing content: •

•

44

Create a Mobile-Friendly Library

Encourage user engagement with your library content. Enable users to: •

Add comments

For app store descriptions, plan for app store updates. App store content must be updated whenever your company updates the app with features or fixes.

•

Provide ratings

•

Recommend content

•

Create collections

Your mobile app’s End User License Agreement (EULA) links to an End User License Agreement. EULA text originates from the legal department, but some companies require that technical communicators host the EULA on the web. If this is the case, plan where to post the EULA, when to provide the link to developers for the apps and app stores, and when to test the links on mobile devices.

•

Use enhanced search

•

Post to their social networks

Edit, Edit, Edit For mobile content on small screens, you must edit ruthlessly. While writing or editing, ask yourself: •

What is the primary purpose of this screen?

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 seconds?

•

Is the information too dense? What can you remove? (Rachel Hinman, http://rachelhinman.com/)

•

Develop mobile style guidelines and adhere to them.

Create Mobile Videos Videos are a helpful way to engage users in mobile apps. A best practice is to post a video with a mobile screencast showing key tasks. Reflector is a useful tool for capturing mobile screencasts, and it now supports Android and iOS devices. With Reflector, you can display a mobile screencast on a laptop or desktop computer, where you can easily edit it. Use Reflector to get the screencast from the mobile device to a laptop. Then use Camtasia or another editing tool to produce the video. An effective mobile video production process for an iPad video edited on a PC: 1. Start Reflector on the PC. 2. Connect the PC and iPad to the same wireless network. 3. Connect the iPad with Mirroring to the PC. 4. Record the screencast on the PC with Camtasia. 5. Edit and publish the video to YouTube. In the video’s call to action, include links to mobile app stores. You can also include the links in the video’s description on the YouTube page. If you include shortened links using Bit.ly, you can track the traffic driven to the app store from your video.

Maximize Video Views A video is effective only if it is seen by the target users. To increase the number of views, collaborate with administrators of your company’s YouTube channels to create mobile playlists that point to your video. On a recent video, the author created playlists on several corporate YouTube channels, including curriculum development, pushing the video to more than 4,482 views worldwide.

Announce videos to your company as they are being produced. You can also spread the word by providing the video URL and description to sales and marketing teams. As teams promote it on their channels, your video will be highlighted in blogs and social networks, and it may be shown at conferences and demos. Periodically, search on the web for your video and product to find third-party posts. Our video was featured as a “Top Pick” on a mobile video app. This honor increased the number of views and provided publicity for the product.

Run a Social Network Campaign Social network posts bring attention to the mobile app and encourage users to download it from the app store. Technical communicators can contribute by posting to the department’s social networks. Before you start your campaign, understand your company’s social network guidelines and policies, and get permission for your campaign. Next, understand your audience and develop your strategy. Create a timeline, decide on the networks, and create a schedule. Additional strategies for social media campaigns are detailed in Marta Rauch’s presentation on Innovations in User Assistance, http://www.slideshare.net/MartaRauch/ rauch-innovations-inuserassistancewritersua2012. Next, plan your posts. To save time and ensure consistency, leverage content you have already developed for the product. For example, you can reuse the new feature points that you developed for the app store as Twitter posts. Before posting, hold a review of your posts and get signoff from stakeholders. 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. Before your campaign, use Bit.ly to shorten links to the app store pages, library, and videos. Later, you can use Bit.ly analytics to track the effectiveness of your posts. Post on your department’s social networks, and coordinate with other social network administrators at your company to share information. Depending on your company’s policy and your target users, you may post on Twitter, Facebook, Google+, Pinterest, Instagram, and YouTube.

2015 STC Technical Communication Summit Proceedings

45

Art, Design, and Visual Communication

Tips for selected social networks: •

Twitter: Use shortened links and include relevant hashtags.

•

Facebook: Post on your department or company’s page. Include pictures to invite engagement.

•

LinkedIn: If your product’s target users are members of groups on LinkedIn, find out which groups they are in, and post there.

•

Google+: Include Google+. It is helpful for SEO (search engine optimization) and is integrated with YouTube. Pictures and videos increase interaction.

•

YouTube: Your Google+ posts are displayed on YouTube and invite engagement directly on your video’s YouTube page.

Get Feedback from Customers Get customer feedback to validate your content. An especially beneficial way to get feedback is through a customer partner program. For detailed information on customer partnering and other ways to get customer feedback, see Marta Rauch’s article for CIDM Best Practices: http://www.infomanagementcenter. com/members/pdfs/reprints/BP09-12MRauch.pdf Key points for customer partnering: •

To find customers, get leads from your company’s marketing, sales, product marketing, and user experience teams.

•

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 suggestions and positive feedback on our mobile content. We then shared a sample of this feedback with stakeholders to validate our contributions to customer satisfaction.

Communicate Wins It is important to communicate your team’s success to internal stakeholders. This helps demonstrate the effectiveness of your content and team. It shows how you contributed to customer satisfaction by increasing engagement with the product. To communicate wins, gather metrics and share key highlights.

Gather Metrics Examples of metrics you can gather and communicate: •

Engagement

•

Follower growth

•

Page views

•

Time on page

•

Actions

•

Downloads

•

Interview feedback

These social networks have built-in effective analytics tools: •

Facebook: View Facebook page insights for your page

•

YouTube: Check analytics for your video to learn which mobile devices viewers are using to watch

•

Twitter: Go to https://analytics.twitter. com/user/TwitterID/tweets

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 is Adobe Site Catalyst.

social networks. The posts give me information in real time to help customers upgrade.” •

Share Key Highlights Share highlights of analytics and customer feedback to communicate results to executives and stakeholders at your company. When executives demo your product, watch the session and post updates on social media with a link to the product. For example, when an executive spoke about the author’s product at the company’s yearly customer conference, the author posted about the session on social networks with a shortened link to the Apple and Google Play app stores. A few hours later, Bit.ly metrics showed that the posts drove 443 visits to the mobile apps on both app stores. Executives, of course, were pleased about the metrics.

Mobile video: “I like seeing the product in use with a live demo in the video.” “Your YouTube channel is my go-to location for finding your videos.” “I subscribe to your video channel and get notifications when new videos come out.”

Conclusion This article describes several effective strategies for delighting mobile customers. Use these best practices to contribute to the success of your own mobile products by creating helpful content for mobile apps, developing videos, and running social media campaigns. Leverage content across multiple channels, measure benefits, and communicate results to add 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 campaign For example, after a customer partnering demo of mobile content, the author shared these quotes from key customers: •

•

Mobile content: “The mobile tour is great. It helps you get started, and has just the right amount of information.” “The mobile content and library are useful.” “I like being able to give feedback and add comments and reviews.” Social networks: “I follow you on all of your social networks. I stay up to the minute and get your RSS feed in my inbox.” “I follow you on LinkedIn and Google+. LinkedIn is my favorite network, and I check it daily.” “I appreciate the great work you’re doing with

The preceding is intended to outline our general 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 material, code, or functionality, and should not be relied upon in making purchasing decisions. The development, release, and timing of any features or functionality described for Oracle’s products remains at the sole discretion of Oracle.

Resources Marta Rauch SlideShare, http://www.slideshare.net/ MartaRauch/presentations Marta Rauch Pinterest boards: http://www.pinterest. com/martarauch/ Developing User Assistance for Mobile Apps, by Joe Welinske The Language of Content Strategy (includes Marta’s topic), by Scott Abel and Rahel Bailie

2015 STC Technical Communication Summit Proceedings

47

Art, Design, and Visual Communication

Managing Enterprise Content: A Unified Content Strategy, by Ann Rockley Content Strategy for Mobile, by Karen McGrane Responsive Web Design, Ethan Marcotte Oracle Application Express Twitter Analytics: https://analytics.twitter.com/ Facebook Insights: https://www.facebook.com/ business/news/pageinsights CircleCount Google+ analytics: http://www. circlecount.com/ Guy Kawasaki, What the Plus Google+ guide, http:// www.guykawasaki.com/what-the-plus/ Guy Kawasaki, Enchantment, http://www. guykawasaki.com/enchantment/

Author Information Marta Rauch Senior Principal Information Developer Oracle @martarauch LinkedIn

personal networks, she has over 165,000 connections and a Klout score of 77. She is in the top 160 U.S. women on Google+. An STC Associate Fellow, Marta has received 15 STC awards for individual and team projects at the regional and international level. She is VP of STC Silicon Valley and a member of the STC Nominating Committee. Marta graduated from Stanford University and earned certification in technical communication from the University of California Extension. Emily Hamer is a principal information developer at Oracle, where she works with different teams to develop content and video-based user assistance for Public Sector Planning and Budgeting and mobile and cloud products. Emily enjoys launching social media campaigns to introduce new products, showcase functional enhancements, and engage customers.

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 challenges for mobile apps, gamification, beacons, augmented 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 contributed 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 Dylan Tuttle

61

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, commitment, 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.

E

verybody’s path to becoming a leader is unique. Some paths are straightforward and relatively predictable while others follow a very haphazard and unexpected route (like mine). However, regardless of the position title (manager, supervisor, team lead, or something else) and the circumstances on how it is achieved, there are certain qualities and characteristics that make potential candidates shine enough for others to take the chance on giving them the extra responsibility that comes with leading others. In this paper, I will discuss some of those key characteristics, describe things that I did to prepare for management, and list activities that you should consider as you prepare for the next potential stop in your career. I will also outline new manager responsbilities and offer some advice on deciding if being a manager is the right fit (it’s not for everyone). Just ahead—Management, YOU.

ager position to lead it—it had just been proposed and created, based on the foundation and trust that I didn’t realize I’d been building within the organization. An unusual but true story.

One Person’s Trip

Leadership Is a Journey

I’ve mentioned that everyone has a different path to leadership. Basically, it’s very difficult to say what a ‘normal’ scenario is for somebody who becomes a new manager (there’s no recipe). Perhaps you work on a team and as a senior member end up replacing an existing manager who resigns or retires. Maybe you work in a growing company and as the most ‘seasoned’ person end up leading an expanding team of less experienced people. Neither of those scenarios applied to my situation. In fact, when I was promoted there was no Technical Communications team (it was a brand new department) and no man-

I believe that leadership is a journey, not a destination. Regardless of the actual position or title (manager, supervisor, team lead, whatever)—it’s just a stop along a greater career path. It’s a road trip!



So how is it that I was able to get a manager position if I didn’t work as part of a technical communication team and wasn’t able to demonstrate any direct ‘on the job’ supervisory experience? Well, I can’t say for sure (you’d have to ask my former manager), but I strongly suspect that there were various experiences and other things I was doing to stand out from others (in a good way) that were key in getting the new job. Plus I was documenting and sharing those experiences, making it clear that I was looking for an opportunity to advance. I’ll talk about these activities in more detail and provide some examples later in this essay.

Of course some trips and the paths and routes taken to advance in a career are bumpier and take longer than others, which is just one part of what make everyone’s journey unique. Many factors can also influence your trip—weather, road conditions, climate, terrain, and so on. I use this analogy to help paint a picture and demonstrate that the step 51

Leadership and Management

from individual contributor to leader is rarely as straightforward and predictable as we think it might (or should) be.

Here are some sample questions:

Preparing for the Trip There are three general things you should do before you decide whether or not you’re ready or want to grab the wheel and get off on the management exit. 1. Take an Inventory Ask key questions so that you understand why you want to advance and to determine how ready you are to start the journey. Do you know where you want to go or just that you want to get moving?

•

What kind of leader are you? Hands off or hands on?

•

Would you rather supervise or be a direct manager? What level of responsibility are you comfortable with?

•

Do you want to continue doing your current job? Do you like producing content and doing things for yourself?

What’s Your Motivation? It’s important to think about what is driving your desire to advance. It’s not always what you expect when you take the time to think a little deeper.

2. Set Your Course Before you hit the road, take stock of your situation and analyze your surroundings to better know your chances of getting the next position and where you’re most likely to find the opportunity. Also look for others who can assist or support you during the trip. 3. Hit the Road Chart your course and start to perform concrete actions and activities so you’re ready to pull off when the opportunity comes up. Pack the car and start driving!

•

Are you looking for more responsibility?

•

Do you want to earn more money?

•

Do you desire more respect or authority to make changes?

•

Are you looking for a change of scenery?

I can tell you that if you answer ‘Yes’ to any or all of those questions, then you don’t necessarily need to be a manager to get those things (and might consider alternate ways to achieve your goal).

Taking an Inventory

What are Your Expectations?

Before you start traveling, it’s important to get a better understanding of the motivations and reasons why you think you want to be a manager (or should be promoted to one). I suggest breaking this analysis into two sets of questions, similar to how you would prepare for an interview.

Each leader or manager position in an organization has different job responsibilities, so you should consider what’s required before you decide to jump in and go for it. For example, you may find that the next-level supervisory role just adds some extra 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 make sure that being a manager is what you really want to do.

Packing Your Bag

Why Do You Want to be a Manager? You need to be able to explain and understand your thinking to this basic question if you want to prepare and be successful.

52

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 angle will help you gauge how prepared you really are to take the next step. The second set of questions can help you explain to others why promoting you is an obvious choice (and also help prepare you improve your odds of getting a more advanced position). 2015 STC Technical Communication Summit Proceedings



Becoming a New Manager

What are Your Strengths? You need to be prepared to give solid reasons and examples of skills that make you stand out from a potential pool of other candidates. •

What Experience Do You Have as a Leader?

How well do you get along with others, both in your group and with other teams?

•

Are you known as a team player or collaborator?

•

Are you considered trustworthy or respected by your peers?

How Prepared are You to Move into a New Role? •

Who could do your current job if you were promoted?

•

Is there documentation of your work to help train someone else?

Setting Your Course Once you better understand what you’re looking for and how well prepared you are, it’s time to look out the window, analyze the landscape, and see who else is traveling on the road. This is also the time to consider reaching out to others who can help you navigate, give directions, or make repairs if something unexpected occurs during the trip (and it’s likely something will come up). Your goal here is to find the next opportunity, pull off, and grab that prime spot before somebody else does. Examine Your Surroundings •

What is the next promotion level for you?

•

Are there any current or expected openings?

•

What sort of competition is out there? Is it the current position holder or others in your group a potential candidate for the job you’re interested in?

•

Who are the most qualified or experienced people who could get the job? Hopefully it’s you.

Identify Potential Tripmates

What People Skills Do You Have? •

Are you close to getting or qualifying for a supervisory or team lead position?

Look Out For Other Drivers

How do these skills translate to being a leader?

Write down examples of experiences that demonstrate how you have led others in the past (with work or other situations, such as volunteering or in a professional organization - like STC).

•

•

Are there others who might support you or act as a reference?

•

Is there an insider who can give you solid information or advice on the position?

•

Do you know someone who might be a mentor?

You want to build relationships with anybody who has already traveled the road or who you could learn from to avoid potholes or find a shortcut.

Hitting the Road Now that you know the road and have packed your bags, it’s time to start moving and charting your course. At this point, you need to be moving forward 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 opportunity. There are two primary things that I did that I believe helped convince the decision makers that I was ready to take my position to the next level (and lead others). First, I did a lot of sharing with my boss and talked about my leadership and professional experiences and accomplishments. In my case, I had been a community STC leader (President of Philadelphia Metro chapter) and presenter who spoke at regional and national events (such as the STC Summit). Additionally, I made sure that my manager knew that I was looking to advance in the company and was prepared to take an assignment or role that would help the company as well as further 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 performed my job as a ‘department’ (of one)—writing down duties and responsibilities. Since I was a lone writer it was important to demonstrate that I was able to self-manage and make decisions with little oversight or supervision. Of course I had to perform and do solid work, but it was noted that I kept busy and worked with little direction while handling issues or getting past obstacles. While accepting additional responsibilities and asking for work, I stayed positive and enthusiastic, worked with other teams, and maintained consistent standards. For example, I created a Tech Comm Style Guide and documented my procedures in a handbook.

make sure the team is doing the job that is expected of them.

So it’s important to document and share your experiences so that others can appreciate that you’re a seasoned and well-traveled driver—that your capable of handling the trip. This gives future decision makers and hiring managers confidence that you can take the wheel in their organization and that you are positioned to be a primary driver who is responsible for the well-being and safety of others (your future team).

Getting Your Bearings Congratulations! If you’ve been lucky enough to identify a management opportunity and given the keys to a a new role, it’s time to settle in and see how this management ride suits you. First things first though, as a new manager you need to focus on the basics and learn the ropes before you become the ‘boss.’ More importantly, understand that being a manager is different than being a sole contributor or member of a team—the buck now stops with you! So what does that mean?

You are not an individual contributor. Although you may continue to have some responsibility for line-level work, in most cases you will not be the one getting your hands dirty, but you have to ensure the job gets finished (and may have to step in to do it).

•

You now are playing multiple roles. You’re not just the star actor anymore, now you’re a director, camera person, editor, producer, screenwriter, and so on—you’ll be wearing multiple hats.

•

You are the compliance checker and enforcer. You have to make sure that you and the team follow company policy and implement the goals and directives of upper management. It’s you that has to explain if the team breaks a rule, doesn’t meet a deadline, or misses something.

•

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, needs support, or doesn’t know how to do something.

Basically, the responsibility, judgment, failures, and successes of the team start and end with you. You no longer are the one who gets the credit, but at the same time you are expected to accept the responsibility for any missteps or mistakes made by you or a member of the team. In the eyes of the organization, you are the last word.

Deciding If It Fits

I’ve said being a manager is different, but how is it different? There are plenty of books and other resources that explain all the big and little differences, so I’m just going to provide a few high-level bullets to show you’re really not in Kansas anymore (or wherever your journey began). You’ll notice that the items I list all start with the word ‘You’—that’s not a coincidence.

54

•

•

You are responsible for others. The work, behavior, and effort of your team falls on you.

•

You are evaluated by the team’s performance. Your individual work or accomplishments are no longer the focus, so you have to

There will be times when everything is clicking (you and the team are hitting all the notes) and then there will be other times when you want Calgon to come take you away (if you’re dealing with personnel issues or putting out fires)—that’s just the swing of being responsible for a team. You should expect highs and lows and that the first few months of being a manager will have challenges that you didn’t anticipate. It’s a big adjustment and difficult to prepare for being a manager beforehand. Give yourself time to learn the ropes, sort things out, and really work at the manager ‘job’ before you decide if it’s really the

2015 STC Technical Communication Summit Proceedings



career path for you—if it’s a good fit, the experience can be rewarding. However, there are people who become a manager and then realize that they prefer being in the trenches, aren’t comfortable with the added responsibility, or dislike the extra overhead, politics, or paperwork. Regardless of the reason, it’s alright to later find out that being a manager is not the right path for you (or not at this time). If that’s what you later decide, trust your instincts, move on to the next opportunity, and consider being a manager just a step along your career journey (like any other position).

Becoming a New Manager

Communication degree and is an active participant and Senior Member of the Society for Technical Communication (including Past President of the Philadelphia Metro Chapter ‘of Excellence’ and 2014 recipient of the Distinguished Chapter Service Award).  Todd believes that service to others is a vital part of personal enrichment and a key component to professional advancement. He is actively engaged with the STC community and enjoys learning, speaking, and sharing his experiences with colleagues. Over the past two years he has presented multiple times at 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, communication, 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 functionality. Spreadsheets are ideal for managing and presenting lists of information. This progression introduces Microsoft Excel tables, formulas, standard and conditional formatting, 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.

I

s your workload too big for sticky notes but the budget’s too small for a complex tracking tool? Learn how to use Microsoft Excel conditional formatting, tables, and formulas to list, sort, and automatically mark priority projects and track your progress. This ubiquitous tool can do more than most of us realize!

This session covers spreadsheet layout for a doc schedule, types of fields and data, formatting, helpful formulas, best practices, and on-the-cheap alternative spreadsheet programs.

•

List your projects in the left-most column, and project data fields along the top in a non-scrolling heading row.

•

Small fonts are your friends. Narrow fonts are especially useful in keeping information compact.

•

For widescreen viewing and wide printing, define the page size as Legal (or a similar wide format).

•

Define the rows and columns as a data table. This enables easy sorting and filtering (explained later). To define your list as a table, select the range of cells, then click Table in the Insert ribbon.

•

Define the first column as sequential row numbers that don’t sort or change order with the rest of the data. This makes it easy to refer to row numbers when discussing the schedule with others.

•

To more easily work with printouts of the schedule, create a header or footer that contains page numbers, print date, filename, and file location.

Assumptions The presentation assumes a familiarity with spreadsheets in general, and Microsoft Excel in particular. Resources are provided, though, for learning basic spreadsheet principles and alternatives to Excel.

Layout Although you can design the sheet however you want, these are some guidelines I’ve used with success: •



Although an Excel spreadsheet can have thousands of columns and over a million rows, try to keep your sheet narrow enough that it can print its full width onto a landscape sheet.

Column Titles (Fields) The fields you define as columns in your sheet will depend completely on your own job’s needs. If 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). You’ll get the clearest understanding of your needs by first starting to use a prototype tracking sheet, then modifying it as you go. Here are some fields to consider: •

Part number (or some unique identifier)

•

Product name

•

Code name (used until product name is official)

•

Deliverable type (user guide, brochure, online help, etc.)

•

Priority

•

Assignments (writer, editor, designer)

•

Goals & gates: Draft due, final due, product ship date

•

Historical: Date entered/requested, date edited, date approved, date sent to press

•

Time measuring: Elapsed time since start (work days vs. true days), time left before due. Hours (for billing), budget (hours or money)

•

Cost: Budget planned, budget used, budget remaining

•

Miscellaneous notes (often the widest field)

Formatting

•

Along with the familiar horizontal alignment formats, in cells you can set the vertical alignment. For some reason, Excel aligns cell content at the bottom by default (who reads from the bottom first?), so change that in any new spreadsheet by selecting the entire sheet and clicking Top Align on the Home ribbon.

•

You can format a cell’s fill color, but you can also format its pattern (for a “shaded” look). Be conservative in applying fill color or pattern—what looks good on-screen may not be readable when printed. And if you print only to black & white, keep that in mind when you’re selecting formatting for cell shading (avoid shades of similar darkness, for example).

•

Try formatting text or shading to mark urgent projects with red, or completed projects with green.

•

To prevent long text from getting truncated at the cell’s border, select the entire sheet and click Wrap Text on the Home ribbon.

•

When using dates, use short date formats to save room. Excel “remembers” the full date (along with the year day of the week), even if the date format you select is a short “xx/xx” version.

•

When using currency, use short currency formats to save room. Excel “remembers” the full money amount, down to whatever fraction you specified, even if the currency format you select is a shortened or rounded version.

You’ll want the data to be dense, but readable, and you’ll want the significance of priority data to stand out. To accomplish this, you can use direct formatting and conditional formatting.

Conditional Formatting Direct Formatting You’re a technical communicator, so you’re already well-versed in basic text formatting. But there are some quirks to Excel formatting to keep in mind:

58

•

You are the audience for this document, so use formats that work well for you.

•

You can edit selected characters/words within a cell, but it’s easiest to apply edits to the cell as a whole. Think of cells as mini-paragraphs; just click to select a cell, then click a format on the Home ribbon to apply to the cell.

Conditional formatting is “programmed formatting” that’s applied automatically when certain conditions are met. The “Starter Spreadsheet” available at bit. ly/simpleschedule contains examples that you can try out and copy. Conditional formatting is powerful, and it’s fun to experiment with. Examples: •

Automatically shade a project’s Part Number cell green when the project’s “Priority” column is marked “A.”

•

Mark the “Due” cell red if the date is less than a week away.

2015 STC Technical Communication Summit Proceedings



Simple Scheduling

•

Automatically draw a progress bar in background of a “% Complete” cell to visually depict the number.

of formulas and functions. Here are some of my favorites: •

AVERAGE Computes the mean value of a range of cells.

•

1. Select the cell(s) to apply the conditional format to.

CELL Can show the sheet’s filename. Useful for headers/footers.

•

2. On the Home ribbon, click Conditional Formatting, then click New Rule.

CONCATENATE Joins several text strings into one text string.

•

3. Select the rule type and parameters, then click OK.

COUNT Counts the number of cells within a range that contain numbers.

•

COUNTBLANK Counts the number of empty cells within a range of cells.

Sorting and Filtering

•

After you’ve defined the data as a table, sort buttons appear to the right of each column label. To sort on any column, click its sort button, then select which order you want the data sorted by.

COUNTIF Computes the number of cells within the defined range that meet the criteria you specify.

•

MAX Returns the largest value in a set of values.

•

You can also temporarily hide rows of data by using a filter. To use a filter, click the column’s sort button, then select the rows to display or hide:

MEDIAN Returns the median value in a set of values.

•

MIN Returns the smallest value in a set of values.

•

ROUND Rounds a cell’s fractional value to a specified number of digits.

•

SUM Adds all numbers in a range of cells.

To apply conditional formatting (this will be demonstrated in the session):

Formulas and Functions Formulas transform the spreadsheet from a record-keeping tool to a computing tool. Formulas automate repetitive tasks and do math for you. You can think of formulas as equations—because that’s what they are, only these equations start with the “=” symbol.

Time functions: •

To enter a formula in a cell (this will be demonstrated in the session):

DAYS360 Returns the number of days between two dates. Useful for counting days remaining before deadline.

•

NETWORKDAYS Returns the number of “business days” (M-F) between two dates.

•

NOW Returns the current date and time, down to the second.

1. Type the equals symbol (=), then type the function name (such as AVERAGE). 2. After the function name, type the range in parentheses (if a range is required).

Best practices

3. Press Enter. The formula disappears, and the value it returns is displayed.

Although you should use whatever process works for you, here are some guidelines I’ve used with success:

When you type a formula into a cell, Excel “remembers” what you typed there, but it displays only the result of the formula. “Functions” are terms you can use within a formula to help it complete its computation (such as “MEAN” to compute the mean value of a range of cells). The “Starter Spreadsheet” available at bit.ly/simpleschedule contains working examples 2015 STC Technical Communication Summit Proceedings

•

Create (and name with the date) a new copy of the sheet (a “tab”) each week.

•

Name the sheets by date (for example, YYYY-MM-DD).

•

Maintain at least one quarter’s history of sheets, archiving old sheets at the end of each quarter. 59

Leadership and Management

•

Save a copy of the sheet each week, named by date, and store in a location that is backed up.

•

Maintain a master project history separate from the doc schedule. The doc schedule itself is dynamic and transitory—it can change daily, and projects can be removed from the sheet as they are completed to prevent the schedule from becoming cumbersome.. A master project history records every project, when it was completed, and who completed it. It can also record where the project’s files are stored, which revision is current, and what changes are requested for the next revision. I only add to the master history when a new project begins and is completed.

•

•

For recording work hours, consider recording only the totals on your doc schedule, and keep the details to specialized time tracking software. (Recording individual, day-by-day hours in the doc schedule can result in numerous columns and an ungainly worksheet.) If your company or department doesn’t already use a part numbering scheme to uniquely identify each project, start now. Unique part numbers simplify record keeping and archiving in a big way.

Additional Tips For a list of cheap/free Excel alternatives, search online or see the list at on bit.ly/simpleschedule. See the same website for more tips on designing doc schedules.

Resources Sawyer, Michael D. “Simplified Scheduling.” Sawyerhome.net (8 May 2015). www. sawyerhome.net/stc/schedule.html.

Microsoft Office Support. “Overview of formulas.” Support.office.com (8 May 2015). support. office.com/en-ca/article/Overview-offormulas-7abfda78-eff3-4cc6-b4a76350d512d2dc. Small Business Computing.com. “4 Free Spreadsheet Alternatives to Microsoft Excel.” Smallbusinesscomputing.com (8 May 2015). www.smallbusinesscomputing.com/biztools/ article.php/10730_3939366_2/4-FreeSpreadsheet-Alternatives-to-Microsoft-Excel. htm.

Author Contact Information Mike Sawyer Documentation Manager Control4 92 West 1565 North Orem, UT 84057 U.S.A. +1.385.209.7164

Author Biography Mike has 20 years of experience in technical documentation as an employee, freelancer, and manager. He loves writing, editing, and designing, and also has a background in human factors engineering and ergonomics. He’s worked for WordPerfect/ Novell, Gateway, and Linksys, as well as many smaller companies and clients. He likes organizing 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 teller (but not at the same time). He graduated in Communications Studies, minoring in English, at Brigham Young University. He completed coursework for his master’s in Human Factors Engineering at the University of South Dakota. He’s lived in California, Idaho, Iowa, and Utah, and served as a missionary in Japan for two years. He has five kids, one wife, five cats, and two litter boxes. 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 challenging 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 acceptance and participation can be improved with thoughtful use of copyright governance. [Disclaimer: The following is intended for informational purposes only. It does not constitute legal advice. Consult an attorney if necessary.]

I

f you have ever edited a page on Wikipedia or written an answer on StackOverflow, then you probably licensed your contribution under the Creative Commons Attribution-ShareAlike 3.0 Unported license. This is consistent with the free culture goal of “creating a commons of freely reusable materials that can be most readily used, shared, and remixed by others.” This may or may not have been your intent. In all likelihood you did this at your leisure and the consequences were benign if not beneficial.

As admirable as free culture goals might be, they may not be the best policy for you or your stakeholders. Consider a scenario where you are basically soliciting users for product development ideas. Telling users that their contributions are licensed under a free culture license might elicit a skeptical response. Open source software projects may be able to do this, but even they are under increasing pressure to require contributor license agreements. This is often the case for both code and documentation. Terms of service are an alternative to contributor license agreements, but it is no longer safe to assume that users are oblivious to terms of service. A recent controversy over Instagram’s terms forced the

company to revise a clause that apparently gave the company the right to sell your photos. The documentary Terms and Conditions May Apply has raised awareness of privacy issues, but ownership of content and the scope of copyright licenses are also under scrutiny as can be seen on the website Terms of Service; Didn’t Read. The following list is a sample of issues monitored by Terms of Service; Didn’t Read under the topics of Ownership and Scope of copyright license: •

Twitpic takes credit for your content

•

Google can use your content for all their existing and future services

•

Couchsurfing keeps the license on your content, even after you close your account

•

Couchsurfing becomes the owner of ideas you give them

•

The copyright license in most terms of service goes well beyond the requirements for operating the service, often including sublicense and perpetuity clauses.

61

Leadership and Management

•

One especially interesting clause in Facebook’s terms states “We always appreciate your feedback or other suggestions about Facebook, but you understand that we may use your feedback or suggestions without any obligation to compensate you for them (just as you have no obligation to offer them).” The fact that Facebook needs to make this explicit is telling.

•

It was 2004 when Tim O’Reilly gave his now famous Web 2.0 manifesto saying that “customers are building your business for you.” Or as others have more cynically put it, “You are the product.” According to Google Trends, interest in Web 2.0 peaked in April

Figure 1. Web 2.0 topic search, Google Trends 2007. The last Web 2.0 Summit was in 2011. While not scientific, it seems safe to say that the Web 2.0 moment has passed. In 2006 the UX expert Jakob Neilsen articulated the 1% rule for participation inequality based on earlier research by Will Hill. It basically states that you can only expect active participation from 1% of users. The general consensus appears to be that you may be able to skew the distribution, but you cannot fight human nature. Rather than question the design pattern of social media and online communities, UX experts appear more than happy to blame human nature and play what amounts to a numbers game.

Early thinkers on the subject of the Internet, such as Ted Nelson, envisioned both read and write functionality for the common user. Long before DITA, Nelson coined the term “transclusion.” His Project Xanadu envisions a system of micropayments for copyright protected works visibly connected by parallel pages. This might seem fanciful, but it serves as a healthy reminder that there are alternatives to the dominant design patterns.

Beyond the Firewall How can you benefit from improved copyright 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. Many popular business philosophies, including Lean Enterprise, Open Innovation, and Customer Development, require some degree of intellectual property sharing. This is often easier said than done. As in any relationship, equity will always be a concern. Appealing to abstract concepts such as “community” or “innovation” is as likely to alienate as inspire. Plain dealing is more likely to elicit a genuine response. While not always necessary, contracts go a long way toward clarifying transaction terms. Software developers are familiar with the code review process. In the case of open source projects, reviewers and even committers may be external contributors. Without contributor license agreements, open source projects are exposed to liability and perhaps more importantly credibility issues with their customers. Increasingly we are seeing documentation 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 consequences for rates of participation. As in any contract,

Figure 2. OpenXanadu (sources only) 62

2015 STC Technical Communication Summit Proceedings



it is a question of fairness. Contracts are always more or less favorable to each party. In addition to the issue of assignment, you would also need to give careful consideration to the outbound license. This is the license under which the material contributed to is offered. It is often assumed that standard copyleft licenses such as those approved by Creative Commons or The Open Source Initiative are the only option. This is clearly not the case as we can see from the terms of service of various providers. The question then becomes why deviate from these apparent standards? The first question to ask is whether your use case requires free distribution. Especially in the case of media, you may want to reconsider the common wisdom that copyleft licenses are the best way to promote your content when nothing prevents citing or linking to your content under standard copyright. You are basically giving permission to republish, which is not necessarily what you want in the case of media. The second question to ask is whether reserving the 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 covetous ways. It would be critical at this point to keep in mind the principle of equity. Is the value you provide greater than or equal to the value you receive in contributions? If it is, then you can rest assured that participation inequality will not be a problem regardless of your choice of license. Georg Greve says of free software that “the expected return on investment comes in the form of strategic independence and lower licensing costs.” In opposition to proprietary software, it is easy to understand the appeal. It is far less obvious who the beneficiary is when the customer is also the product. As Greve goes on to say, it depends on where you are in the stack. Fortunately you are not obliged to use standard licenses. You could even write your own license. Whether evaluating terms of service, contributor license agreements, or standard licenses, you will want to consider the use case and how favorable the terms are for each party. Copyright governance will impact your authorship model, which in turn will influence your design pattern. While not yet well understood, it is almost certain that participation can be improved if the principle of equity is applied to copyright governance.

Copyright Licensing for Review and Reuse

The use case of templates is especially interesting. Templates can reduce effort while preserving rhetorical freedom. They also do not require any special markup or processing. While there is nothing preventing the free distribution of templates, there also are no obvious incentives. Can a clear distinction be made between reuse and republishing rights? At what point does a derivative work based on a template become an original work? What is the difference between a simple template such as a purchase order and a generic document narrative? At what point does the concept of authorship breakdown? These questions are the result of capabilities introduced by digital media. The potential of these new capabilities have not yet been fully explored. The technical writer is on the frontier of new media. Be bold. This material is based upon work supported by the National Science Foundation under Grant No. IIP1416066. Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author and do not necessarily reflect the views of the National Science Foundation.

Resources Google Trends (1 May 2015). http://www.google. com/trends/ Harmony Agreements (1 May 2015). http://www. harmonyagreements.org/ Mader, Stewart. Wikipatterns (Indianapolis, Ind.: Wiley Publishing, Inc.), 2008. Project Xanadu® (1 May 2015). http://xanadu.com/ Stim, Richard. Getting Permission, 5th edition (Berkeley, Calif.: Nolo), 2013. Terms of Service; Didn’t Read (1 May 2015). https:// tosdr.org/

References “Frequently Answered Questions.” The Open Source Initiative (1 May 2015). http://opensource. org/faq “Terms of Service.” Facebook (1 May 2015). https:// www.facebook.com/legal/terms “Understanding Free Cultural Works.” Creative Commons (1 May 2015). http:// creativecommons.org/freeworks

2015 STC Technical Communication Summit Proceedings

63

Leadership and Management

Atwood, Jeff. “Attribution Required.” StackOverflow (1 May 2015). http://blog.stackoverflow. com/2009/06/attribution-required/ Derksen, Bryan, et al. “Web 2.0.” Wikipedia (1 May 2015). http://en.wikipedia.org/wiki/ Web_2.0 Greve, Georg. “What makes a Free Software company?” freedom bits (1 May 2015). http://blogs.fsfe.org/greve/?p=260 Hoback, Cullen. Terms and Conditions May Apply. 2013. Kaplan-Moss, Jacob. “Contributor License Agreements.” Jacob Kaplan-Moss (1 May 2015). http://jacobian.org/writing/ contributor-license-agreements/

Author Biography Dylan Tuttle is no stranger to career change. He started in the finance industry as a stock options trader. He then worked for a nonprofit workforce development agency. In his most recent role, he was responsible for the development of a small business training program. It was at this point that Dylan realized that training alone could not address the need for improved knowledge management capabilities. He is currently developing a web application to expand external working memory and improve the ability to assimilate new information. It is an interpersonal wiki for informal learning and self-publishing.

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



2015 STC Technical Communication Summit Proceedings

Copyright Licensing for Review and Reuse

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 Scott Prentice

93

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 experience of a team of eight writers tasked with converting 10,000 pages of unstructured legacy content into structured (“intelligent”) DITA content. We describe problems encountered 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.

T

his session describes the experience of a team of eight writers who moved over 10,000 pages of technical content to DITA. A critical factor in the success of the project was to hire the right partners for certain tasks. If you are considering a move to DITA, you can benefit from the knowledge we gained on when and how to hire expert partners.

Project Initiation What problem were we trying to solve by moving to DITA? Here’s a brief description of our content crisis: •

1. 1. Project initiation. Identify and address the content crisis driving the need for content migration.

Duplication of authoring efforts among different groups in the company, (training, technical support, and documentation) produced overlapping content that was difficult to maintain.

•

2. Content analysis. Assess the condition of existing legacy content and specify requirements for the new system.

Content lacked standardization and consistency, making it difficult to share content among groups.

•

Device proliferation. We had to make sure that our content could be easily viewed on mobile devices as well as in web browsers. Most of our customers didn’t currently view our content on mobile devices, but we knew that was coming soon.

The session describes all major phases of the project:

3. Training and pilot. Develop expertise and create the necessary processes for working with the new system. 4. Content conversion, migration, and cleanup. Not everything can be automated, but there are ways to minimize the amount of manual work required. 5. Lessons learned. Takeaways for writers and managers.

To solve these problems, we discovered eight tasks for which we had no in-house expertise, so we got help for those tasks from outside partners (Figure 1). Because individual stakeholders (including ourselves) had only a limited grasp of the big picture, 67

Tools and Technology

our first task was to obtain a detailed analysis of the problem from a neutral outside observer. Enter Partner #1.

Figure 1. Eight tasks, four different partners

Content Analysis Our work with Partner #1 gave us an excellent birdseye view of our problems, a list of design goals to solve them (Figure 2), and a consensus amongst the stakeholders on where to go next. Significantly, a consideration of our design goals revealed that our existing topic-based content management system (CMS) did not meet our needs. Thus began our search for a new CMS vendor.

Writer Training and Pilot 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. 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, but it was well worth it. The pilot was an essential “shakedown cruise” where we got to practice the knowledge we’d learned in the two weeks of training. And, although we had known about DITA for a year before the change, and some of us had even read books about it, we discovered that there was no substitute for trying out DITA on our own content.

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.

Figure 2. Bird’s-eye view of content problems and the design goals required to solve them

3. Import the DITA content into an instance of the new CMS on a staging server.

CMS Vendor Selection After an exhaustive search, we found two vendors whose products met our requirements. Both products 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 winner 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. 5. Transfer the cleaned-up DITA content to the production server. 6. Use scripts to publish the DITA content on the production server to PDF and to different online output formats (HTML Help, WebHelp, HTML pages, and so on). Unfortunately, our collaboration with Partner #2 for conversion scripts did not work out well. As shown in Figure 4, the conversion script could not distinguish a step from a paragraph within a step, but also duplicated the text. Because of the poor quality of the converted content, cleanup required far more resources than expected. The consultant we hired for the cleanup work (Partner #4) did an excellent job, but we unwittingly gave her more work than she could complete during her six-month contract. Eventually, we had to spend more than two additional years of writer time on cleanup.

performance of Partner #2 is particularly revealing. Although they did an excellent job at training us in DITA and helping us develop our information model, they lacked the necessary expertise in script-writing. We saved money upfront by hiring them for script writing, but it worked out to be more expensive in the end. Our takeaways:

Figure 4. Typical example of content conversion

What went wrong? To begin with, we probably overestimated the script-writing expertise of Partner #2, a company that was primarily focused on DITA training. And we certainly underestimated the complexity of writing conversion scripts.

•

On-site DITA training saved us countless hours over trying to develop an information model and implement DITA after learning it from books or generic DITA classes.

•

Scheduling the six-month pilot project immediately after training was an essential step in getting us up to speed on DITA and on our new CMS. The excellent support we got from the CMS vendor during the pilot was a major factor in the success of the 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 inexperienced partner can cost you years of writer time.

•

Even with the inexperienced partner, it was still worthwhile to get outside help.

•

Don’t underestimate the complexity of writing scripts for content conversion and publication.

•

Manual cleanup is no fun. Take a look at the converted content in Figure 4 and imagine cleaning up thousands of procedures with those defects.

Partner #2 did a slightly better job on the publication scripts, but once again, we underestimated the complexity of the task. Surely, we thought, publishing 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 the successes and failures of our collaborations. The

Figure 5. Our partnerships worked very well—with two exceptions

2015 STC Technical Communication Summit Proceedings

69

Tools and Technology

References Davis, Nicki. “Case Study: The Value of Partnership during Conversion.” Data Conversion Laboratory, Inc. (18 June 2014) http://www.dclab.com/webinars/case-study-the-value-of-partnership-duringconversion.

of the Association for Computing Machinery, the User Experience Professionals Association, and the American Chemical Society.

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 writing 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 saving 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 studies to find out exactly what users needed. At her next job, she initiated usability testing and made significant 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 professional 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 reStructuredText/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 software developers, system architects and testing engineers is needed. However, reStructuredText’s lack of distinct topic types and semantic tagging weighs against it being a suitable choice for many large-scale documentation projects.

I

n recent years many documentation teams have shunned the use of semantically-rich languages such as DocBook and Darwin Information Typing Architecture (DITA) in favor of lightweight markup languages such as Markdown and reStructuredText. Lightweight languages are easy to learn, easy to read, and easy to write. They are especially popular in the realms of open source and Web-application development, particularly with newer startup companies where the documentation is often created by the developers themselves. By using a lightweight language, developers can create and manage good-looking documentation using the text editors and file-versioning tools they are already familiar with.

First using a semantically-rich markup language (DITA published using the DITA Open Toolkit); second using a lightweight markup language (reStructuredText published using the Sphinx documentation framework). By comparing the results, I will present some pros and cons of using lightweight markup languages versus semantically-rich languages for documenting large, complex projects. But before describing this experiment and examining the results, let’s define what we mean by ‘lightweight markup’. What are lightweight markup languages used for? What problems were they designed to solve?

But what about professional technical communicators working on existing large, complex documentation sets? Should we follow this trend? Should we throw away our fancy XML editors, our DTDs, our Content Management Systems, and go lightweight?

What is Lightweight Markup?

To try and answer this question, I performed an experiment. An experiment where I created two versions of the same example topic-based document.

“…a plain text formatting syntax…a software tool…that converts the plain text formatting to HTML.”



John Gruber, the creator of Markdown—probably the most popular lightweight markup language— described his creation as:

71

Tools and Technology

We can apply this definition to lightweight markup languages in general. Whether we are looking at reStructuredText, or AsciiDoc, or Markdown itself, what these languages all have in common is that they have a plain text formatting syntax, and they come with software tools to convert that formatted text to HTML. And increasingly these software tools—often referred to as ‘toolchains’—can convert the plain formatted text to other formats, such as PDF and even XML. The quickest way to get the gist of a lightweight 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 tool for the Mac is Mou and for Linux ReText). The nice thing about MarkdownPad2 is that its 2-pane interface shows your plain text in the left pane and a preview of your rendered HTML in the right pane. Figure 1 shows an example Markdown document typed into Markdownpad2. This example shows some of the available Markdown syntax: •

Headings. Precede your heading with hash marks; one hash signifying heading level 1, two hashes heading level 2 and so on.

•

Numbered list. Precede each list item with a number followed by a full stop.

•

Code block. Indicate code blocks by indenting each line by at least 4 characters (commonly 1 tab stop). In the case of a code block within a numbered list—like that shown in

Figure 1—indent each line by at least 8 characters (2 tab stops). •

Inline code. Wrap inline code with backtick characters (`).

The important thing to note is that even without the colored syntax highlighting and live preview provided by the MarkdownPad2 editor, the actual Markdown text is easy to read. You can open it in the simplest of text editors—like Windows Notepad or Mac TextEdit—and it will be perfectly readable and easily editable.

How Did Lightweight Markup Come About? I would argue that there are two historical drivers that led to the development of lightweight markup. First, there is a long history of formatted plain text. Since the early days of computing, content creators have made use of informal methods—such as underlining headings with dashes, and using asterisks to indicate bullets—to add some structure to their plain text documents. Second, the arrival of the World Wide Web brought a need for fast, simple alternatives to hand-coding HTML. Lightweight languages such as Markdown [1] reStructuredText [2] and AsciiDoc [3] were developed to meet that need.

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 Document, Two approaches From my first exposure to a lightweight markup language—to Markdown—I was hooked by the refreshing simplicity of a lightweight approach. But I wanted to see how such an approach compares with one of the documentation approaches I am more familiar with, for example with DITA. Is a lightweight approach really up to the kind of complex documentation jobs I’m used to—where large documentation sets for products with multiple parallel maintenance releases are the norm? What I decided to do was create an example document using DITA, and see whether I could recreate it using a lightweight markup language. Although the sample document would be small, I decided that it should at least test the lightweight approach’s support for the following five features of DITA that I consider to be particularly useful for large, complex document sets: •

Mechanism for logically arranging and linking topic files

•

Support of distinct topic types

•

Basic reuse

•

Mechanism for including metadata

•

Semantic tagging

For the actual test document, I created—using the Oxygen XML Editor tool--a simplified version of the example ‘Comstar User Guide’ that JoAnn Hackos uses in her book Introduction to DITA [4]. I then attempted to recreate this user guide using a lightweight markup language.

For this experiment I chose to use reStructuredText as my lightweight language in conjunction with the framework tool Sphinx—the same combination used for the Python programming language documentation [5]. So, let’s go through each of the five features and see how the chosen lightweight approach shapes up.

Mechanism for Logically Arranging and Linking Topic Files DITA maps provide a simple means for organizing your topic files into the structure you want (Figure 2. DITA maps allow us to create a topic hierarchy2). In the words of JoAnn Hackos: “DITA maps are the backbone of DITA. Maps provide a mechanism for ordering topics and creating a topic hierarchy.” [4] In order to logically arrange a set of reStructuredText files, and to provide basic navigational links between the topics, we need a framework. And that framework is provided by Sphinx. Using a Sphinx/ reStructuredText approach, the equivalent to the DITA Map is the ‘master document’, by default named index.rst. In the master document file, you define a table of contents tree—in reStructuredText parlance a toctree ‘directive’—comprising the sequence of files you want to include in your document. However, the toctree allows only a flat sequence of files to be specified. So to recreate the topic hierarchy of the example document, one option would be just to abandon the separate topic files and include, for instance, a concept and its 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 be included inside another file (Figure 3. Using the reStructuredText toctree and include directives to create a topic hierarchy3 and Figure 4. An example HTML page created from two reStructuredText topic files using the include directive directives to create a topic hierarchy4). Of course, if later we wanted to restructure our document, or reuse some of the parent topics in other master documents, some manual maintenance of these include directives would be required. On a small project, this would be trivial, but could become prohibitive on larger projects.

looked up quickly by the user. By having distinct topic types—each with their own subset of markup tags—it makes it easy to maintain a consistent look and feel across large document sets. This is particularly important for large-scale complex projects where content might be created by multiple technical communicators and where the users need consistency in order to find the information they need quickly to perform their tasks. The Sphinx/ ReStructuredText approach offers no equivalent to DITA’s distinct topic types—when you open up your text editor and start writing a topic there is no structural guidance, you are free to use any of ReStructuredText’s markup and directives.

Distinct Topic Types

Basic Reuse

Another feature of DITA useful for complex documentation is its support of distinct topic types. The three basic topic types allow us to create task topics to answer “How do I…” questions, concept topics to answer “What is this about?” questions, and reference topics to provide information that can be

Content reuse mechanisms offer possibilities to reduce the complexity and volume of our documentation. DITA provides a rich choice of reuse options—including sophisticated mechanisms for transcluding content from dedicated reuse files, and 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



wanted to see if Sphinx/RestructuredText can replicate DITA’s simplest reuse mechanism: topic reuse. To do this in my DITA document was straightforward. I simply created a new DITA map, and added topicref tags pointing to the topics that I want to reuse (Figure 5. Reusing topics in different DITA maps5)

Can Lightweight Markup Punch above its Weight?

been built as HTML—including ones that were not referenced via the master document toctree or related include directives. In other words, I was generating HTML for some topics that I didn’t want to include in my new document (Figure 7). So a cleaner and more satisfactory solution was to create a new source directory for the new project, copy the files I 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 configuIn 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 “Metadata is one of the best ways to improve the created topic files (Figure 6). 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 metadata is the element. This topic-level element provides a container for topic-level metadata. For example, you can place keywords for your topic within the container which will render as keywords in the metadata of your HTML output. For the purpose of the experiment, I wanted to see if keyword metadata can similarly be added to a reStructuredText topic. And the answer is that it can. In reStructuredText you use a meta directive to define metadata such as keywords to be rendered as HTML metadata (see Figure 8. reStructuredText topic file with metadata8).

Semantic Tagging Like the other lightweight languages AsciiDoc and Markdown, reStructuredText lacks the semantic richness of DITA. For example, with reStructuredText, we can mark up code elements, commands, filenames, and user interfaces by surrounding them

by back ticks. But in effect, all we are doing is tagging these items with formatting information. In contrast, with DITA tags, we can distinguish between command names, variable names, user input values and much more. And we can make use of this information in our DITA deliverables. For example, we can use styling to differentiate user interface elements and so on. reStructuredText’s lack of semantic tagging can also make it more difficult to create consistent step-bystep procedures and reference topics. In the case of a step-by-step procedure, a writer using a good DITA editor can use the tags available in the standard DITA topic task as a template. The basic topic task provides tags for task prerequisites, post requisites, examples within steps, and many other content structures that your task may need. And the editor will ensure that you put these tags in the correct place, greatly helping with consistency. With reStructuredText on the other hand, you are commonly faced with a blank page and a much more limited set of markup tags with which to fill that page.

Conclusions So, should you use a lightweight approach for your next project?

Figure 7. Rendered HTML from the reStructuredText topic reuse experiment.

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 colleagues. Collaboration between software developers, architects, testers and the technical communica-

Figure 8. reStructuredText topic file with metadata 76

2015 STC Technical Communication Summit Proceedings



tion team can become easier. Since we are asking our colleagues to write, edit and comment using plain text, they can use whatever text editor they use for their software creation tasks. And what’s more, the same versioning tools, the same review tools, the same issue-tracking tools might be used for both software and documentation. But the seductive simplicity of lightweight markup comes at a price. They are semantically poor. For example, the basic Markdown language is little more than a shorthand for a subset of HTML. The lack of distinct topic types also makes it more difficult to maintain a consistent look and feel across a document set, especially in products where the documentation might be written my many different contributors from across the organization. In addition, the lightweight approaches I have looked at so far do not lend themselves easily to content reuse. I conclude that lightweight languages such as reStructuredText offer an attractive option for projects where a lot of content input from non-techcomm colleagues is needed. However, at least in the case of reStructuredText, a lack of distinct topic types and semantic tagging weighs against it being a suitable choice for many large-scale documentation projects I would like to thank Dr JoAnn Hackos for her kind permission to use example DITA topics from her book Introduction to DITA. [4]

Resources Deza, Alfredo. “Easy and beautiful documentation with Sphinx” ibm.com. http://www.ibm. com/developerworks/library/os-sphinxdocumentation/ (accessed April 3, 2015) “MarkdownPad” markdownpad http:// markdownpad.com. (accessed March 13, 2015)

Can Lightweight Markup Punch above its Weight?

[2] “reStructuredText” docutils-sourceforge http:// docutils.sourceforge.net/rst.html (accessed April 3, 2015) [3] “AsciiDoc Home Page” methods http://www. methods.co.nz/asciidoc/ (accessed April 3, 2015) [4] Hackos, JoAnn. Introduction to DITA, Second Edition (Denver, CO: Comtech Services, Inc.), 2011 [5] “Sphinx Python Documentation Generator” sphinx-doc. http://sphinx-doc.org/index. html (accessed April 3, 2015) [6] Bellamy, Laura, Michelle Carey and Jenifer Schlotfeldt.DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA (Upper Saddle River, NJ: IBM Press), 2012

Author Contact Information Raymond Gillespie R&D System Verification Engineer Nokia Networks [email protected] +36 30 411 1516

Author Biography Raymond Gillespie, an STC Senior Member, has 20 years’ experience in the field of information technology. For the past 14 years, Raymond has lived in Budapest, Hungary working as both a software engineer and a technical writer, mainly in the fields of telecommunication, medical imaging and navigation software. He currently works for Nokia Networks as an R&D System Verification Engineer and has a special interest in the testing of procedural documents. Raymond holds an MSc in Information Management from Lancaster University Management School (UK).

“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 writers 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? 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 version-control softwares available. It is widely used both by the open-source community, and by major corporations. Its popularity continues to grow, in part, simply because it is already popular, with copious resources available for anyone with a search engine and the desire to use it (Stephen, 2015). In the simplest terms, version control software is software that manages changes to a collection of data (Chacon, 2009). This management is vital to large projects undergoing concurrent development by multiple teams. Version control software mitigates the risk of inevitable conflicts, and ensures that changes to one section of a file do not overwrite changes in another section. In addition, Git and other systems like it provide change histories, store copies of each file and its revisions, and maintain file and directory structures. It is important to note that, before writers can successfully work in Git, they should have at least a basic grasp of the command line interface (CLI). The CLI allows users to run text commands that trigger actions in a computer program. Working on the CLI may seem daunting to first-time users, but is actually



as simple as entering text (a command) and pressing the Enter key.

Data in Git Git stores the canonical set of data for any given project in a database, known as a repository. Each repository includes an object store and an index: •

The object store contains the project’s actual files (in the Git world, “blobs” and “trees”) and the records for each change that has been made to those files (“commits,” each identified by a SHA1 value) (Loeliger, 2012).

•

The index records the directory structure for all of the files in the object store (Loeliger, 2012).

To work with a repository’s data, users run the ‘git clone’ command from the CLI on a local computer that has Git installed. This command copies (clones) all of the supplied repository location’s data and creates a new directory within the working directory. The new repository that you have copied contains all of the same files as the source repository, but will maintain its own unique history when changes are made (Loeliger, 2012).

79

Tools and Technology

Branches The ‘git branch’ command creates “branches.” Branches are copies of the cloned main repository

ency with the team. A regression into waterfall, with the writer excluded from the team’s development process, is to be avoided at all costs. 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. Some teams prefer to maintain separate branches for different areas of development (for example, a team might have separate branches for backend development, testing, and text changes). This offers the benefit of allowing development to happen independently of low-impact text changes, and can be expedient when working toward a close deadline, or when working on a particularly difficult-to-test project. However, if the entire team does not maintain awareness of all branches of development, this method can unfortunately result in the writer becoming sidelined. It may also cause some areas of development to fall behind others, since new changes will need to be merged into each branch from the team repository separately. On other teams, writers may work within, and commit changes to, the same branch as the team’s developers. This structure ensures that the writer’s work is transparent to the rest of the team, and is treated as a fully-qualified part of the Agile process. It also ensures that the branch is as up-to-date as possible with regards to new changes. It requires additional diligence from the writer, however, to ensure that changes do not lag behind or hinder development or testing, impacting the team’s overall workflow. Many writers may find it useful to work in a combination of these two options, to tailor workflows to the needs of the work. In either scenario, of course, the most important part of the process is transpar80

Figure 2. A complex Git structure, possibly for a product with many Agile teams or separate projects. Once changes are merged into the main repository, other users or teams can access and update the changed files, or merge these changes into existing branches. This allows for simultaneous development by any number of users or teams, because users can work in close proximity without the fear of overwriting each other’s work. Git has the capacity, too, for more elaborate structures. Individual teams might have multiple branches or their own repositories for different projects or releases of a product, all coming from one main repository.

Git Archaeology Though of course it was created with software development in mind, Git’s functionality isn’t only useful to software developers. It is also extremely advantageous to technical writers who work as members of Agile teams. •

Changes are accessible by everyone on a team, generally in near-to-real time.

•

Writers have the tools to engage in their own “archaeology.”

2015 STC Technical Communication Summit Proceedings



Git Started: Hands-On Git for Agile Writers

•

•

Writers can update interface text or make other changes directly, before development finishes. Git acts as a sort of technical training ground, ensuring that writers get the chance to spend time in the code and better understand their product from the inside out.

Git’s archaeological tools allow writers to perform their own investigations of changes, sometimes without needing help from teammates at all. This frees up valuable time that was previously spent “chasing down” information, and provides technical data in a much richer context.

Git Blame The ‘git blame’ command drills down into the current state of an individual file in the repository (Loeliger, 2012), and displays each line of the file’s current state. For each line in a file, Git displays a shortened form of the commit’s SHA1 value, the committer’s name, the date and time of the change, and the line number. The commit ID can be used with the ‘git log’ command to find more information about other changes in that commit.

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 in time and another (a “diff”). This command is very similar to the ‘diff’ program (Loeliger, 2012), and is, perhaps, the most useful archaeological tool in Git.

Figure 4. An example of the ‘git blame’ command and its output. 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 structures 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 allows comparisons to be made not only against 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 development period, or even the changes made in a given workday. For example, if a writer knows the last commit at which a document was updated, running a diff between that commit and the current commit will reveal all of the possible changes to functionality that need to be included in updates to that document. This becomes even easier for updates to documentation for versioned software, if all of the major versions are available to compare.

Figure 5. Some possible uses of the ‘git log’ command and its many options. from a writer’s own team and changes from other teams that have been merged into a working branch.

GIT LOG Run without options, the ‘git log’ command displays a list of the commit information for every commit in the current repository or branch (Loeliger, 2012). This command is more helpful when used with additional options, of which it has an extensive list. •

2015 STC Technical Communication Summit Proceedings

Providing a specified number of commits will display a pared down list of only the most 81

Tools and Technology

recent commits. Often, it is only necessary to view the most recent log entry. •

Running the command with a specific commit’s SHA1 value (perhaps as retrieved from the ‘git blame’ command) displays the information and commit message for that specific commit.

•

When run with a specified filename, the command displays only the commits that changed that file.

•

Other useful options include limiting the list to commits by a certain author, before or after a certain date, or options that modify the information displayed for each commit.

Figure 6. A ‘git log’ entry for a single commit. •

The ‘git log’ command’s one failing as an archaeological tool is that it generally depends on the commit message to provide more detailed information. Because each committer writes his or her own commit message, this message is not always all-inclusive or even particularly helpful.

Best practices state that commits should include a short summary, followed by a detailed explanation of the reason for the change and its effects (Chacon, 2009), but these guidelines aren’t always followed. In most cases, however, it should provide introductory information, and the name of the committer to ask if more detailed information is needed.

might, however. The ability to read the code and find specific landmarks, particularly comments and printed text, is far more important than the ability to write even a small script or function. Writing functional code is even more helpful, of course, but it shouldn’t be considered a prerequisite by any means. The usefulness of Git, of course, only goes as far as the individual writer’s ability to work in it independently. Luckily, this is a tool that you can practice in easily: •

If you have access to your company’s codebase, pick a previous change to research, and practice following the inevitable rabbit trails 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 service sites like the extremely-popular GitHub.

Resources Olsson, Aske and Rasmus Voss. Git Version Control Cookbook (Birmingham, UK: Packt Publishing), 2014.

References Chacon, Scott. Pro Git (New York, NY: Apress), 2009. Loeliger, Jon and Matthew McCullough. Version Control with Git (Sebastopol, CA: O’Reilly), 2012. Stephen. “The Case for Git in 2015.” ‘Net Instructions (20 Jan. 2015). http://www. netinstructions.com/the-case-for-git/

Hands-On Changes A basic understanding of Git opens the door for Agile writers to make and commit their own changes to a software project’s UI text, or other small text changes. For example, rather than relying on developers to update text to Global English standards after development, a team’s writer could use a simple text editor and Git to commit all of the textual changes iteratively, as part of the development process. Of course, the ability to do this relies on having some familiarity with the coding language in which the text is embedded. Writers do not need to approach this in the same way that a beginning developer 82

Author Contact Information Sarah Kiniry Technical Writer II cPanel, Inc. 3131 W Alabama Ste 100 Houston, TX 77098 +1.713.742.3617

Author Biography Sarah Kiniry is a Technical Writer for cPanel, Inc., a web hosting software company. In this role, she provides full documentation support for an Agile 2015 STC Technical Communication Summit Proceedings



Git Started: Hands-On Git for Agile Writers

development team, as well as participating in content strategy and other initiatives for the company as a whole. Recently, she spearheaded a project to completely rewrite the company’s extensive SDK documentation, 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 audience 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 software 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 understanding of iterative development models across industries provides valuable insight into technical 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.

T

here are two basic types of development models: sequential and iterative. Often, new development models are presented in opposition to older models, which are criticized for being too sequential and not iterative enough. A close examination, however, reveals that even those development models generally presented as sequential contain iterative phases, and were originally intended as guidelines that should be adapted for specific requirements and situations, rather than implemented in a rigid way. This false opposition is indicative of a novice-level approach that can lead to decreased quality and efficiency. The successful application of development models requires an expert-level understanding that facilitates flexibility and adaptation. Applying development models with this approach can lead to substantial process improvements.

Development Models Across Industries A development model is a conceptual representation of the processes used to create a target product, condition, or other deliverable. Development models exist for a wide variety of fields and industries, including software development, instructional design, design and innovation, social change, project management, land management, engineering, health

care, and more. (See the section titled Development Models Across Industries for a list of examples.) A comparison of models across industries reveals that three primary phases are universally important: •

An initial phase for gathering information and planning

•

A design and development phase

•

A phase or multiple phases for testing, review, and refinement

Types of Development Models There are two basic types of development models: sequential and iterative. Sequential development 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 by repetition and revision. Iterative models explicitly provide “for changes in requirements and design as the project progresses.” [1] Sequential and iterative models are often presented in opposition to one another in order to highlight the advantages of one over the other.

85

Tools and Technology

Two Opposing Models in Software Development Two archetypal examples of sequential and iterative development models related to software development are Waterfall and Agile, respectively. A typical graphic depiction of the Waterfall development model appears very linear. Often, graphic depictions of this model do not visually indicate any iterative stages.

is often cited as a source of the Waterfall methodology, [4] reveals that the intended spirit, while wellplanned, top-down, and highly monitored [5] was also highly iterative. “We had a need to… recognize that things would not work well the first, second, or third time, and therefore that much independent testing was needed in successive phases; to create development tools that would help build products and test tools and to make sure they worked…” [5] 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 evident 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 apparent dichotomy between these two models is often overstated. A retrospective written by Herbert D. Bennington, one of the authors whose early work

Within the field of instructional design, two other development models are being presented in a similar oppositional relationship: the Instructional Systems Design (ISD) model, which has evolved into the

86

2015 STC Technical Communication Summit Proceedings



widely-used Analyze, Design, Develop, Implement, Evaluate (ADDIE) [6] model, and the Successive Approximation Model (SAM). [10]

Iterative Development Models and Process Improvement

more creativity, and addressed effective stakeholder involvement.” [10]

In 2012, Michael Allen, an industry leader in instructional design, published a book called Leaving ADDIE for SAM: Faster, Better Learning Product Development. Allen’s stated goal was to develop a model that increased the quality of eLearning products and resulted in products that were truly beneficial to learners. [14]

A closer examination, however, reveals that both the original ISD model and ADDIE are highly iterative and designed to be adapted to specific situations. The original ISD model, based on work conducted in the 1970s at Florida State University for the military [6], included 5 general phases and 19 detailed steps, several of which call for iterative review and refinement. [11]

According to Allen, “The ADDIE process is past its prime. It was developed long before Agile and other iterative processes that have introduced greater efficiencies in design and development, fostered

ADDIE, which is often simplified to include only the top-level steps of the original ISD model, is typically shown in ways that highlight the cyclic nature of the 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 highly iterative, and can be adapted, as needed, to implement process improvements and ensure that projects are successful.

Novices in any field have a tendency to latch onto any guidance and follow that guidance in a literal, step-by-step manner. Only later, when they become 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 adjustments 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 systemic 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

Figure 6. Analyze, Design, Develop, Implement, and Evaluate (ADDIE) Model [13]

The Dangers of Using Development Models The largely artificial dichotomy between Waterfall and Agile and between SAM and ISD reveals one of the dangers in relying too heavily on a static interpretation of any development model—a rigid misapplication of the model, based on a lack of dynamic understanding and flexibility, that leads to processes that are ineffective, time-consuming, demoralizing, and result in a low-quality product. The intent of these process models is to create checkpoints for refinement and re-evaluation, in order to ensure both product quality, and efficicency of production. But these checkpoints only work if they are dynamically defined by the capabilities and needs of the company, as well as the needs of the consumer. In terms of process improvement, it is critical, then, to remain flexible and to implement the model in ways that are adapted to particular risks, requirements, products, resources, and other factors. As stated by Hannum [6], one of the original developers of the ISD model in the 1970s, “…developers who are relative novices… may cling to the model and treat it as a paint-by-numbers approach. 88

When used correctly and expertly, models can be tremendously useful, and can lead to measurable process improvements. Process improvement is the proactive effort to identify, analyze, and modify processes and standards to increase the quality, efficiency, consistency, and return on investment. Implementing processes and standards can be difficult, as many are resistant to change and because, so often, processes and standards end up creating an additional burden on employees and creating points of congestion in the development process. A defining characteristic of quality processes is that they enable success and effectively make employees’ lives easier by reducing duplicate work, reducing the amount of time required to decide on minutia, and by providing tools that make it faster and easier to create consistent products. Development models can facilitate clear communication and be used to demonstrate important concepts related to design, development, and the development cycle. Propper use of development models can facilitate: •

Higher morale through unity, a shared vision, clear expectations, and increased success.

•

Transitions that are seamless and, therefore, cost-efficient, because new team members

2015 STC Technical Communication Summit Proceedings



Iterative Development Models and Process Improvement

and leaders have a clear vision of the overall process and where in the process the project is at any given time. •

Identifying points of congestion in the development process; that is, points at which development is slowed or stalled. [7]

•

Identifying excessive back and forth; that is, points at which the process of communication is taking an inordinate amount of time. [7]

•

Identifying sources of defects and duplicate work; defining the phases of a process makes it easier to identify the point at which defects are being introduced. [7]

•

Maintaining consistency, which is a fundamental component of quality. [7]

Development models can also be used to demonstrate: •

Quality—Because iterative development models are based on the premise that a product will need improvement after initial development, the model can be used to demonstrate that, while the product may clearly need additional improvement, quality expectations are being met for a given stage in the process.

•

Efficiency—Development models can be used to show where a project is in the development cycle, and demonstrate how the pace at which requirements are being met fits with expectations (schedule).

•

Trajectory—Development models can communicate to others what will happen next. “A process model answers two main questions: What should be done next? For how long should it continue?” [9]

Iterative Model Adapted for Technical Information Design Adapting iterative development models for technical information design can lead to significant process improvements. In technical information design, deliverables are often developed in support of other, primary products. For example, a training manual may be developed for customers in support of a software product, which is the company’s primary deliverable. This means that, quite often, the development process for technical communication

is subsidiary, tangential, and often considered a necessary expense and an inconvenience. Because of this, it is critical that technical information designers be extremely adept at flexibly adapting to the restrictions imposed by schedule, resources, requirements, audience, and other factors. In addition to the basic phases common to nearly all development models (gathering information and planning; design and development; and testing, review, and refinement), I typically incorporate two additional phases: Synthesize and Prepare.

Synthesize Analysis is a common early phase in development models, and refers to the detailed examination of the elements or the structure of something—analysis is typified by separating something into smaller, more manageable components. Synthesis, in contrast, refers to combining elements together to form something new. The process of synthesis is critical to quality information design, and is the phase during which you can incorporate audience analysis, task analysis, user experience, and other concepts in order to reformulate information and ensure that it is useful and high quality. The spirit of synthesis is akin to what is often called design thinking, a solution-based, creative approach that emphasizes empathy and user-centeredness, reframing all possibilities, and prototyping. [16] The advantage to adding this step to the process is that it provides an opportunity to innovate, and to move away from patterns that have been repeated simply to avoid disrupting the status quo.

Prepare Preparation refers to the process of creating the tools, process guidelines, and standards that will ensure the actual development process proceeds quickly and efficiently. Often, development begins without any preparation, which inevitably leads to re-work and defects—without standards (and, therefore, without having defined what constitutes a defect), it is impossible for developers to create quality, consistent deliverables. The products of the preparation phase include templates, style guidelines, graphic asset libraries, user interface kits, quick-reference guides, and more. The advantage to adding this step is tremendous: iterations (such as feedback from internal and external stakeholders) can be concentrated 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 final deliverables, and small details can be decided on, documented, communicated, and, when possible, created, so that developers (writers and designers) can focus more on the decisions that require their expertise. As with all development models, this model should be tailored to the requirements of a specific situation, and, within each phase, iterations should take place as often as common sense allows. Iterating early and often has positive consequences in that, not only does it reduce the number of defects and the amount of re-work, it also generates buy-in, facilitates collaboration, and reinforces a sense of teamwork. In addition, using an iterative development model for technical information design allows you to develop technical information that is usable and can be delivered much earlier than if it is developed without iterations.

Development Models Across Industries Many managers base important strategic business decisions on industry trends as they are presented in mass media, rather than on in-depth scholarly research; therefore, the development models listed below include those found in both scholarly (peer-reviewed) and non-scholarly sources. Across industries, there are many development models, including: •

Agile (Industry: Software Development)

•

Analyze, Design, Develop, Implement, Evaluate (ADDIE) (Industry: Instructional Design)

•

Building Information Modeling (BIM) (Industry: Construction)

•

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 of the Project (Industry: Construction)

•

Consensus Flowchart (Industry: Conflict Resolution)

•

Converge Voice of the Employee (VoE) (Industry: Process Improvement)

•

Creative Process Model (Industry: Design)

•

Design Thinking at SAP (Industry: Software Development)

•

Scientific Method (Industry: Sciences)

•

Simplex Innovation Process (Industry: Design)

•

Sims and Jones’ (2003) Three-PhaseDesign (3PD) (Industry: Instructional Design)

•

Social Action and Scientific Inquiry (Industry: Marketing)

•

Spiral (Industry: Software Development)

•

Strategic Development Process (Industry: Industrial Design)

•

Design Thinking Process (Industry: Design)

•

Dick and Carey Systems Approach Model (Industry: Instructional Design)

•

Successive Approximation Model (SAM) (Industry: Instructional Design)

•

Dual Process of Reasoning (Industry: Health Care)

•

Top-Down Design (Industry: Software Development)

•

Engineering Method (Industry: Engineering)

•

•

Good Manufacturing Practice (GMP) (Industry: Pharmaceuticals)

Typical Stage-Gate Process (Industry: Construction)

•

Waterfall (Industry: Software Development)

•

IDEAL Model (Industry: Process Improvement)

•

•

Instructional Systems Design (ISD) (Industry: Instructional Design)

A Web Site Designed: Milestones, Involvement, Importance, and Timeline (Industry: Web Design)

•

•

Integrated Sustainable Design Thinking Process (Industry: Ecology)

Web-Based Instructional Design Model (Industry: Instructional Design)

•

Iterative Optimization Cycle (Industry: Marketing)

•

Life Cycle Model (Industry: Project Management)

•

LX Design Process (Industry: Manufacturing)

•

PDCA Cycle (Industry: Quality Assurance)

•

PMBOK Process Model (Industry: Project Management)

•

Practice of Conversation (Industry: Land Management)

•

PRINCE2 Process Model (Industry: Project Management)

•

Progressive Problem-Solving with Action Research (Industry: Social Change)

•

Project Management (Phases) (Industry: Project Management)

•

Quality Enhancement Cycle (Industry: Quality Assurance)

•

Scientific Method (Industry: Sciences)

References [1] Hamilton, Richard L. Managing Writers: A Real World Guide to Managing Technical Documentation. (Fort Collins, CO: XML Press), 2009. [2] Hughey, Douglas. “Comparing Traditional Systems Analysis and Design with Agile Methodologies.” (Copyright 2009. Accessed 28 April 2015.) http://www.umsl. edu/~hugheyd/is6840/waterfall.html. [3] GlobalTeckz. “Characteristics of Agile Methodology in Software Development.” GlobalTeckz (Copyright 2015. Accessed 28 April 2015.) http://blogs.globalteckz.com/ characteristics-of-agile-methodology-insoftware-development/. [4] Wikipedia. “Waterfall Model.” Wikipedia. (Accessed 29 April 2015). http:// en.wikipedia.org/wiki/Waterfall_ modelhttp://en.wikipedia.org/wiki/ Waterfall_model. [5] Benington, Herbert D. “Production of Large 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/usccse83501s.pdfhttp:/sunset.usc.edu/csse/ TECHRPTS/1983/usccse83-501/usccse83501s.pdf.

[15] Sites, Richard. “Be a SAM Superstar with ‘The 12 Days of SAM’.” Allen Interactions (Copyright 26 November 2014. Accessed 28 April 2015). http://info.alleninteractions.com/ be-a-sam-superstar-with-the-12-days-of-sam.

[6] Hannum, Wallace. “Instructional Systems Development: A 30 Year Retrospective.” Educational Technology 45:4 (2005): 5-21. http://dose.wallacehannum.com/ISD%20 Retrospective.pdf.

[16] Platner, Hasso. An Introduction to Design Thinking: Process Guide. (Stanford, CA: Institute of Design at Stanford). Accessed 28 April 2015). https://dschool.stanford. edu/sandbox/groups/designresources/ wiki/36873/attachments/74b3d/ ModeGuideBOOTCAMP2010L.pdf.

[7] Berg, Rob. “Why Process Modeling?” Journal of Insurance Operations. (Copyright 13 June 2011. Accessed 28 April 2015.) http://www. jiops.com/06/2011/why-process-modeling/. [8] English, Stuart. “Design thinking–Value innovation–Deductive reason and the designers choice.” Design Research Society Conference, Lisbon (2006) 1-4. http:// www.iade.pt/drs2006/wonderground/ proceedings/fullpapers/drs2006_0180.pdf.

Author Contact Information Tina M. Kister, PMP Senior Technical Information Designer University of Florida (Graduate Student) 2338 River Park Circle Apt. 1836 Orlando FL 32817 +1.435.260.1565

[9] Boehm, Barry, and Wilfred J. Hansen. “Spiral Development: Experience, Principles, and Refinements.” Special Report CMU/SEI2000-SR-008. Pittsburgh, PA: Carnegie Mellon Software Engineering Institute), 2000.

Author Biography

[10] Allen, Michael. Leaving ADDIE for SAM: Faster, Better Learning Product Development. (Alexandria, VA: American Society for Training and Development), 2012. [11] Branson, Rober K., Gail T. Rayner, J. Lamarr Cox, John P. Furman, F. J. King, and Wallace H. Hannum. Interservice Procedures for Instructional Systems Development: Phase II—Design. (Tallahassee, FL: Florida State University Center for Educational Technology), 1975. [12] Clark, Donald. “ADDIE Timeline.” Big Dog & Little Dog’s Performance Juxtapositon (Copyright 13 July 1995. Accessed 28 April 2015). http://www.nwlink.com/~donclark/ history_isd/addie.html.

Tina M. Kister is a technical writer and designer whose passion is combining quality content with great design. With experience in a wide range of fields, including natural sciences, instructional design (military), health care, engineering, construction, fine art, advertising, and more, she specializes in a cross-discipline approach that embraces best practices across industries, and seeks to take quality technical information and make it compelling and pleasing. She is currently working on a Master’s degree in Mass Communications with a focus on Web Design and Online Communications at the University of Florida.

[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-SAMeLearnChat-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 prototypes. If you’re looking for a single file deliverable that does it all, EPUB may be for you.

Let’s Start at Page One

W

hat is an EPUB? It’s is an ebook file format that can be read on almost every device and platform: desktop, laptop, tablet, phone (and perhaps someday your watch or refrigerator!). It requires the installation of a reader application (ereader) or the use of a dedicated device that has a reader application built-in. Inside an EPUB is a collection of XHTML, XML, CSS, and media files wrapped up in a “zip” archive (conceptually like a CHM file that you’re probably familiar with). It’s a nice neat little package of content and formatting that can be easily provided to users who can add your ebooks to their online libraries for reading whenever needed. An EPUB is a self-contained deliverable that defines the content, navigation, and formatting of the ebook. Because of this it’s perfect for documentation that needs to be available for off-line reading. But an EPUB can be oh so much more than “just an online book,” and that’s what we’ll discuss here. The EPUB specification is maintained by the IDPF (International Digital Publishing Forum). EPUB became an official standard in 2007, superseding the older Open eBook standard (from 1999). Since then, EPUB 2.0.1 was approved in 2010, and the latest specification, EPUB 3, was approved in October 2011. As of June 2014 EPUB 3.0.1 was approved

which includes a fixed layout (FXL) format as well as support for Indexes. The EPUB 3.1 draft is currently available for review, which adds a number of new features around scripting, media, and accessibility.

EPUB 3 is the Key The thing that changed EPUBs from being “just an online book” to something much more was the introduction of EPUB 3. EPUB 3 is based on HTML 5 and CSS 3, which opens up a huge array of formatting, layout, and interactivity options that were previously not available. Prior to EPUB 3, scripting (use of JavaScript) was explicitly discouraged by the specification, and was thus not supported well in ereaders. EPUB 3 reverses that by stating that scripting is supported as defined in the HTML 5 and SVG specifications. It’s important to note that while scripting is now “supported,” it is optional for “Reading Systems” (ereaders) to implement. However, because of the focus on interactivity, most ereaders will support a certain level of scripting. From a security standpoint, each “Content Document” (an XHTML file in the EPUB) is treated as a separate “domain.” This means that the rules of cross domain scripting apply as they would on 93

Tools and Technology

a website, limiting what you can access from any given document. (It appears that this may change with EPUB 3.1 as they are considering enabling client-side cross-origin requests as defined in the W3C CORS specification.) The use of scripting includes the ability to leverage many of the JavaScript libraries that are available for performing special purpose tasks. One library of particular interest is jQuery. This can be very useful for enabling interactivity with document content as well as dynamically modifying the content based on the ereader screen size or orientation. There are also libraries that make it easy to generate charts and graphs from raw data, as well as manipulating SVG graphics. The options are virtually limitless. Through the inclusion of HTML 5, EPUB 3 supports SVG and MathML, as well as embedded audio and video. An EPUB can include Media Overlay Documents which make use of the SMIL specification (Synchronized Multimedia Integration Language) to allow the synchronization of audio with the highlighting of document content. This provides for a “read aloud” EPUB that may be useful in various situations, specifically for educational books and to assist individuals with print disabilities. CSS 3 provides extensive formatting and language support. This means that ereaders should support bi-directional text (left to right and right to left), as well as vertically oriented text. It should also support special properties of vertically-oriented text. Media queries are also supported, which greatly simplifies the implementation of a “responsive” EPUB. One of the new features offered in the EPUB 3.0.1 specification is the Fixed Layout format (known as FXL). This was intended to be used to create 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 is required. This is just a small sampling of the new features available through EPUB 3. Because of this, I like to say that an EPUB is a “website in a box”!

Ereader Features EPUB reader applications and devices will typically provide a standard set of navigation features, which means that you don’t have to implement them your94

self, as you might when developing a website. The following features can be expected in most ereaders: •

Table of contents. Based on the TOC information you provide in the EPUB

•

Bookmarks. Most ereaders will provide some way for the user to place bookmarks for easy access at a later date.

•

Reader notes. Many ereaders will provide the option for the user to make notes and highlight passages or words in the content.

•

UI customization. Most ereaders will allow user-defined setting of fonts, font size, and colors (background and font)

Additional navigation features may be available and implemented in various ways: •

Search. Most ereaders have something called “Search”, but it may in fact be a pageby-page “Find” rather than a proper full text search. Oddly enough, most mobile ereaders will have a better search implementation than desktop ereaders.

•

Index. Because this is in the EPUB 3.0.1 specification, you should start seeing ereaders that support the new Index functionality. However, as of this writing, there are none that I’m aware of.

Because these features are all implemented slightly differently, you should not rely on one particular implementation. You should test as many ereaders as you can, and provide the results to your end users. When you offer an EPUB as a documentation deliverable, you should list a handful of recommended ereaders, but design the EPUB to be functional on as many ereaders as possible.

Layout Implementations Given the functionality and layout options now available with the EPUB 3.0.1 specification, the following fundamental layouts can be achieved: •

Paged model. This is the “traditional” ebook layout, where the content flows from page to page and fills the available screen space. This is a good choice for many types of content, and is more likely to render properly on the widest array of ereaders.

2015 STC Technical Communication Summit Proceedings



EPUB: One Format for All Deliverables

•

•

Fixed layout (EPUB-PDF). This new layout option added with EPUB 3.0.1 can provide an EPUB that looks and functions just like a PDF. While there are no tools that will create this type of EPUB, it can be created “by hand” or possibly through scripting and automation. With a little pressure, we may be able to convince tool vendors to support this type of output. You might logically ask, “if this looks and functions just like a PDF, why not just use a PDF?” The only viable reason I can think 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 and you can make use of scripting. In reality, the use case for this is a stretch, but it’s good to be aware that this type of thing is possible. Keep it in the back of your mind and you never know when it’ll find a sensible use. Vertically scrolling (EPUB Help). This option makes use of scripting and CSS to force onto one page all of the content for a document that would normally span multiple pages. If the “overflow” property is set to “auto,” the page will scroll vertically, just like it does in a traditional compiled Help system like HTML Help or Java Help. By doing this you’ve basically got a single-file deliverable Help system that will run on all platforms and devices. With the apparent demise of HTML Help, many people are left looking for the next way to deliver online Help. Java Help is an option, but it has problems of its own. The only other option is some type of “web help” 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, but for others it doesn’t really fit their needs.

One Format for All Deliverables? With EPUB 3, this format can (theoretically) provide support for all of the common techcomm deliverables. •

User guides. A good choice for both the traditional paged layout as well as the vertically scrolling topic-based model.

•

References. Likely best suited for the vertically scrolling topic-based model.

•

Learning and training material. Could benefit from the vertically scrolling topic-based model enhanced with scripting and forms for interactivity. Would also make use of embedded audio and video.

•

Online help. Most likely suited for the vertically scrolling topic-based model. Would benefit from the ability to open an EPUB on a specific topic to provide context sensitivity.

•

Print-ready documents. Ideally suited for a fixed layout EPUB.

Issues and Limitations As with all good things there are always limitations. Currently, none of the publishing tools support the more interesting EPUB 3 features. This means that you’ll probably need to hand-code for anything beyond simple formatting in a traditionally paged EPUB. Hopefully this will change as tool vendors see the benefits of offering more interesting and useful features. The other problem is that the reader applications and devices all support varying levels of the EPUB 3 specification. This will limit what you can actually provide to your end users, and will restrict the readers that they can use. Until these issues are resolved, especially with regard to the tools, these ideas will not provide truly viable publishing options that are likely to be adopted on a large scale. But they are worth watching and experimenting so that you’re ready to move when it makes sense to do so.

Useful Internet Resources IDPF – EPUB 3.0.1 Specification. – http://idpf.org/ epub/301 IDPF – EPUB 3 Specification. – http://idpf.org/ epub/30 IDPF – EPUB 2.0.1 Specification. – http://idpf.org/ epub/201 Castro, Liz. – http://www.pigsgourdsandwikis.com/ eBook Architects. – http://ebookarchitects.com/ resources/ ePrdctn on Twitter. – https://twitter.com/#!/ search?q=%23eprdctn

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 created 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



2015 STC Technical Communication Summit Proceedings

EPUB: One Format for All Deliverables

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 Stephen Van Esch

109

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 effectively, 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 communicating electronically and provides suggestions for overcoming these problems.

Introduction

E

lectronic media as a means of disseminating information have become ubiquitous. Almost all technical and scientific communication today is conducted electronically (Dabbish, Kraut, Fussell, et al 2005; Louhiala-Salimen 1999). Recent research on where and when messages are read and the number 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 reading emails (Marketing Charts Staff 2014). Users check their smart phones for email approximately 150 times a day (Mujamdar 2013). The typical corporate email user receives about 105 emails per day (Radicati Group 2011). With the demand for the Apple watch outpacing production (New York Times 2015), it is evident that emails and texts are migrating to the new medium. While watches have not been around long enough to collect data, it is estimated that these devices will at least parallel Smart phones as the device of choice for reading messages.

This paper discusses the problems in communicating technical and scientific information. Messages are ‘information-poor,’ writer- rather than reader-oriented, and a-synchronous. The paper looks specifically at these problems as they relate to the communication that occurred between the engineers and managers involved in the BP/Horizon Deepwater oil rig explosion.

Information Poor Emails and text messages are often ‘information-poor’ (Ekroth 2014). Writers fail to include background information and details, increasing the potential for misunderstanding as well as requiring both the writer and the responder to expend an increased amount of time writing additional threads in a chain in order to obtain all of the information needed to make a decision or to do something. (Conversation threads related to the same subject create a chain of emails or text messages with participants responding sequentially to each other).

99

Training and Research

In Figure 1, which relates to the preparation on the BP/Horizon oil rig to cap the well, Dobbs apparently has not received any background information that would have provided her with an understanding for the decision to use a 7”liner. Morel provides her with a basic explanation but there is apparently more that she might want to know as he adds “If you want more details, let me know.” Thus, she may need to continue the chain. Furthermore, Morel does not provide a response to her question about an SOR so she may need to repeat the question in an additional thread. Writers often fail to provide sufficient information because of the pressure to provide an immediate response to a request (Morel responds to Dobbs request within 20 minutes). They also omit necessary information because of their tendency to conflate social media communication with that of business.

Pressure to Respond Instantly Both managers and employees expect an immediate response to their messages, creating an electronic communication overload (Jackson 2012; Barley 2011) which for want of a better name I shall call ECSS (Electronic Communication Stress Syndrome). Many employees are expected to be on call 24/7, regardless of whether they are in an office, having dinner with their family or at an off-site conference. This has resulted in messages being read and responded to quickly, with as few words as possible and without much thought (Skovhold 2009). Often writers are typing at the same time that they are walking along an office corridor, eating lunch, or cooking dinner. Apple’s ads proclaim the device’s ability not only to “tap” the wearer immediately when a message arrives, but to provide the wearer with the message “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 time and the length of the message will become even shorter than they already are.

Conflating Social Media Conventions With Business Correspondence Writers often fail to include background information and detail because they mistakenly conflate elec100

tronic messaging with social media. Twitter with its 140 character maximum, Facebook, Linked In, and Pinterest are all minimally worded. Writers also often omit necessary information because they perceive their readers as being similar to their readers on social media sites. Sites, such as Facebook and Linked In, are composed of closed groups of people in which certain knowledge or interests are held in common. A group of individuals who share similar experiences and knowledge, composes a “high context” culture. The term was introduced by the anthropologist Edward Hall (1976) in his book Beyond Culture. Communication within these sites involves “high context” messages in which background information and details are often omitted because it is assumed (correctly) that readers are knowledgeable in the topics under discussion. A problem in communication occurs when writers mistakenly believe that their audiences--employees, managers, clients and subcontractors in large corporations and organizations—are similar to their readers on Linked In and Facebook, high context groups that have similar interests and vocations. They are not. In technical/scientific business environments, readers may be located in different geographic locations, have different specialties and be assigned to different divisions. They often need background information and elaborated details to understand a message. When writers fail to realize that they are writing in a low rather than a high context environment, they may omit information their readers need to complete a task or make a decision. Recognizing the pressure to respond and the time it takes away from a task, Couch, working on the BP/ Horizon oil rig, indicates in the email in Figure 2 that the reader should not respond until he could fill the request. Pat responds about 1 ½ hours later but Tom doesn’t check on the message until 3 hours later and, when he does, he makes further requests.

Writer-Based Orientation The conflation of social media correspondence with business communication causes other problems. By (con)fusing the style of social media with that of business/technical correspondence, writers create writer- rather than reader-based messages. The term writer-based prose was coined by Linda Flower (1999) to define texts in which the writer writes for him/herself, ignoring the reader’s needs and failing 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: Sent: To: Cc: Subject:

Morel, Brian P( Tuesday, March 30,2010 10:54 AM( Dobbs. Sarah; Hafle, Murk E( PINEDA, FRANCISCO( 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

(((((7((((((7/13/2015(5:25(PM(((((( (

101

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 STC Technical Communication Summit Proceedings (((((9((((((7/13/2015(5:25(PM((((((

(

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

(((((10((((((7/13/2015(5:25(PM(((((( (

2015 STC Technical Communication Summit Proceedings



Effects of Electronic Media on Technical/Scientific Communication

to account for the reader’s prior knowledge and reading style and process. This orientation may result in the interjection of the “I” aspect of social media into a technical/scientific message. The writer may ramble, include irrelevant and personal information as well as fail to provide for readers’ reading patterns. Tendency to ramble. The tendency to ramble not only increases the wordage in a message, but may delay the presentation of the main point, creating a text that may cause readers to stop reading which is probably what occurred when the NASA team received the letter in Figure 3. The letter was written to men who were working 24/7 to try to figure out the location of the damage and the size of the damage caused to the Columbia Shuttle when a piece of foam came off on liftoff and hit the spacecraft. The letter contained the best guess of all the information coming in but it was hidden in the middle of the very long introductory paragraph (highlighted by me). The Commissioners charged with investigating the accident concluded that those to whom it was sent had probably never read far enough into the message to find his conclusion (Columbia Accident Investigation Board 2003). Inclusion of Personal Information. The (con) fusion of social media genres with technical/ scientific ones often leads writers to include personal information that is not related to the focus of a message, resulting in a TMI response (Too Much Information). The email thread in Figure 4, which occurred just before the BP/Horizon oil rig blowout, is a prime example of this error. It was written by an engineer on the rig to a manager on land. In light of the results of the problems discussed in the email it is spine chilling. Failure to provide for readers’ reading patterns. Previous research has indicated that people read hard copy in a “T” pattern, reading the first paragraph and them skimming down the middle of the following paragraphs. New research indicates that people reading emails and texts follow an “F” pattern (Nielsen 2006), reading the first sentence, skimming the remainder of the paragraph, reading the beginning of the second paragraph and then skimming down the left margin of the remainder of the document. If important information is included in the middle, it is usually missed.

A-Synchronous Communication Because electronic correspondence tends to be brief and often omits necessary background information and details, it is a poor medium for communicating complex information or providing a forum for conflicting ideas. However, it is used for just these purposes. Rather than a face-to-face meeting or a telephone discussion, people prefer to use electronic media, believing mistakenly that emails and texts provide the same kind of two-way communication that a telephone provides. But the perception that electronic communication is two-way and that conversations occur simultaneously and in real time is false. In most cases, they do not. They are a-synchronous (Ashley 2003). During a telephone conversation, a person can question an aspect of a description, ask for the definition of a term or request a fuller explanation of a topic and receive an immediate response, even if it is “I don’t know or “I’ll get back to you.” However, during an email or text conversation, the communication can be suspended before a response is made. Of the approximately half of all messages that people read, only about one third of these ever receive a response (Skovholt 2009). Yet writers not only want a response but want it immediately. This is seldom the case. The average time for a response is approximately 28 hours (Dabbish 2005). The gaps in time between messages in an email chain have numerous causes. Participants often leave a chain before it is concluded because they have turned to other work. Whether or not a person responds to a message immediately is usually determined by a person’s perceptions of the importance of a message. Other criteria include the amount of time required for writing a response. Messages requiring more than a quick response are often put aside to be worked on later (Stack 2009). Although reading and responding to a message requesting attendance at a meeting can be done in this fashion, reading and responding to a message that concerns a critical engineering decision, such as the one in Figure 4, often cannot be. Because of the ease of sending electronic messages, other forms of media are rejected. Yet, if issues are complex or open to misunderstanding, multiple forms of communication, 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 during a single time slot, not over a period of time. Laura Stack, President of an international consulting company in Denver, Colorado, claims that “Communication becomes richer as you add human elements like voice, tone, facial expression and physical expression.” She has developed a flow chart ranging from person to person communication for ambiguous, long, or difficult messages to letters and reports for clear, simple messages. She places email in the middle of the range (Stack 2009).

Conclusions and Recommendations To avoid some of the problems associated with electronic media, writers should keep the following recommendations in mind: 1. Place the most important information at the beginning of an email. 2. Remember the reader’s ‘F’ reading pattern. 3. Include all necessary information in a single thread. Don’t make the reader have to request more information. 4. Consider readers’ prior knowledge, wants and needs, and provide readers with the necessary background information and details they need to make a decision or do something. 5. If the message requires you to spend time on a response, notify readers that you have received their message and will get back to them as soon as possible. This relieves you from some of the pressure to respond to the writer, it prevents you from giving the writer only partial information in an effort to respond quickly, and it relieves the writer’s anxiety, wondering if you received the message. 6. Follow the conventions for business/technical correspondence. 7. Refrain from including personal or irrelevant information. 8. Consider communicating by telephone or in-person when issues are complex.

106

References Ashley, J. (2003). Synchronous and A-Synchronous Communication Tools. Retrieved May 2, 2015, from: http://www. asaecenter.org/Resources/articledetail. cfm?itemnumber=13572. Barley, S. R, D. E. Myerson, and S. Grodal. (2011). Email as a Source and Symbol of Stress. Retrieved from http://web.stanford.edu/ group/wto/cgi-bin/uploads/2011%20 Email%20as%20a%20Source%20and%20 Symbol%20of%20Stress.pdf. Columbia Accident Investigation Board. (2003). Report vol 1. Retrieved May 2, 2015, from http://govinfo.library.unt.edu/caib/news/ report/pdf/vol1/full/caib_report_volume1. pdf. Dabbish, L. A., R. E. Kraut, S. Fussell, and S. Kiesler. (2005). Understanding Email use: Predicting Action on a Message. Retrieved May 2, 2015. http://www.cs.cmu.edu/~kiesler/ publications/2005pdfs/2005-Dabbish-CHI. pdf. 2005. Ekroth, L. (2014). Have Email Conversation Problems? Retrieved from http://donmorris.com/article/ have-email-conversation-problems. Flower, L. (1999). Writer-based prose: A cognitive basis for problems in writing, College English, vol. 41, no. 1, pp.19–37. Hall, E. (1876). Beyond Culture. New York: Anchor Books, 1976. Jackson, T. (2011) Email Stress. Retrieved from http://www.profjackson.com/email_stress. html 2012. Louhiala-Salminen, L. (1999) From Business Correspondence to Message Exchange: What is there left? in C, Nickerson and M. Hewings (Eds) Business English: Research into Practice. New York: Longman. pp 100-114. Marketing Charts Staff. When Smartphone Users Check Email During the Day. Retrieved from www.marketingcharts.com/wp/online/ when-smartphone-users-email-during-theday/html. March 2014. Mujumdar, A. (2013). Smartphone users check their phones an average of 150 times a day. Retrieved from http://tech.firstpost.com/ news-analysis/smartphone-users-checktheir-phones-an-average-of-150-times-aday-86984.html. 2015 STC Technical Communication Summit Proceedings



Effects of Electronic Media on Technical/Scientific Communication

New York Times. (2015). Apple CEO Says It’s Hard to Guage Smartwatch Demand. Retrieved from http://www.nytimes.com/ reuters/2015/04/27/business/27reutersapple-results-watch.html .

Engineering Education Conference in Sheffield, England.

Nielsen, J. (2006). F-shaped pattern for reading web content. Retrieved from http://www. nngroup.com/articles/f-shaped-patternreading-web-content/. Radicati Group, (2011). Email statistics report, 20112015. Retrieved from http://www.radicati. com/wp/wp-content/uploads/2011/05/ Email-Statistics-Report-2011-2015Executive-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-ofcommunication-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--Technical 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 documentation 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.

C

onsider how you would complete this sentence: “The goal of a technical communication product is to….”

While you will receive a different answer from different technical communicators, I would expect that most answers would coalesce around the idea that the product should assist the user solve a problem that is plaguing them right at that moment. Clear instructions on dealing with a particular issue are one of the primary ways in which we assist users solve their problems. These can be delivered through a manual, online help, tooltips, or any number of other avenues but their goal is the same: assist the user past their point of difficulty.

A Change of Mindset Needless to say, the goal of instructional design and training is not to assist the user past the point of difficulty. While much of technical documentation may be considered reference material that should be consulted in a time of need, training and the techniques instructional designers use to create effective training are used to bring about a change in behaviour. Essentially, build a new pattern of behavior that is either completely new or replaces an old pattern of behavior. So how can we change the way we as technical communicators approach training materials? From my

own initial forays into developing training materials, I can attest that my first “courses” were really just repackaged manuals with next and previous buttons and a few quiz questions thrown in for good measure. Approaching instructional material from the perspective of documentation and user assistance can obviously lead to courses that are little better than tossing a manual to a learner and calling it a day. So what are some fundamental changes a technical communicator can make to their mindset when approaching instructional material? A few places to start: •

Think it terms of performance improvement. What learner behavior needs to change?

•

Make the learner an active participant in the process. Whether it’s e-learning or in-class training, how can you get the participant involved?

•

Consider the goal of the learning. Should the user recall something specific? Perform a procedure? Solve a particular problem? Each of these goals requires a different instructional approach.

•

What are the criteria for success? How will we evaluate success?

This list is not exhaustive but it should help you explore ways of presenting your training in a more effective manner. 109

Training and Research

Writing Learning Objectives There is a significant amount of effort that goes into creating an effective training. These include learner analysis, needs analysis, and task analysis. Each of these could occupy a paper in their own right. However, many technical communicators have extensive experience in audience and and task analysis so we can instead focus on one of the most effective technique that technical communicators can use to make their training materials more effective. This will also keep technical communicators from straying into the habit of creating products designed to get users past the point of difficulty instead of changing their behavior. Effective learning objectives are one of your most powerful tools to keep you focused. They will ensure your training material includes the appropriate material at the appropriate level. They will also 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 should be able to do when they have completed a segment of instruction.” (Smith & Ragan, 2005, p. 96). Note that the learner must change their behavior, not simply get through the task: “Learning is a cognitive process that leads to a capability that the learner did not possess prior to instruction.” (Smith & Ragan, 2005, p. 96). So what can we do to create effective learning objectives? A good learning objective contains three parts. •

•

•

A stem. A stem is the first part of your learning objective and communicates at what point the objectives will be achieved. For example: “At the end of this module, you will be able to…” A verb. An action verb that suggests the form of assessment. While beyond the scope of this document, note that different verbs are used for different outcomes. For example, listing a set of tools would assess their knowledge of something while identifying a set of tools would assess their analytical abilities. An learning statement. The learning statement sets out what the learner will need to do to demonstrate mastery of the material.

Upon the completion of this module, you should be able to identify the tools in the standard toolbox issued to all service technicians.” Circling back, lets consider how this would help us create effective training. This learning objective would: •

Give us a way of assessing learner success at the end of the module.

•

Help us craft effective questions. For example, instead of multiple choice question with a list of tools you might instead choose a matching question with pictures of tools and accompanying words.

•

Help us craft effective content. For example, you would include images and descriptions of the tools. You would not include information about how they receive the tool box or the colour of the toolbox.

A Different Profession We have barely scratched the surface of what goes into making effective instructional content. This is not surprising as instructional design is it’s own profession. But with organizations looking for technical communicators that can wear many hats and technical communicators looking for new opportunities, changing our mindset and then leveraging our area of expertise (writing!) today’s technical communicator can significantly improve their training products and their increase their value to their company.

Resources Smith, P.L., & Ragan, T. J., (2005). Instructional Design. Hoboken, New Jersey: John Wiley & Sons Inc. “Learning Objectives: Stems and Samples.” http:// www.educationoasis.com/instruction/bt/ learning_objectives.htm Armstrong, Patricia. Bloom’s Taxonomy, Vanderbilt University. http://cft.vanderbilt.edu/ guides-sub-pages/blooms-taxonomy/ Waller, Kathy. Writing Instructional Objectives. http://www.naacls.org/docs/announcement/ writing-objectives.pdf

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 wastewater treatment. Stephen has a Masters degree in Education specializing 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 Louise Tincher

153

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, training, and even product demonstrations. In fact, planning a consistent experience across all of these will help your customers be more successful and save rework.

S

oftware user assistance includes all materials that help to make users successful, including: Help, manuals, quick start guides, job aids, white papers, tutorials, videos, and sample projects. Sample projects that customers can use to learn your application informally are not only educational; they can also serve as sales tools and proofs-of-concept.

•

Learn what the product is capable of doing.

The Sample Project Team

What is a sample project? They vary depending upon the product. Sample projects can be (or include) templates, completed projects (or parts of projects), modules, an interactive website, even code samples. The best sample projects should demonstrate different functionality, best practices, and features—while remaining easy-to-use.

Since sample projects have a number of objectives, and (depending on the product) technical challenges, the team working on the sample projects should span a number of departments. The Product Management, Marketing, Software Development, Web Development, Quality Assurance, and Information Development departments should all be included at various phases of the project. Everyone should agree on goals and responsibilities before 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 illustrate. Several concepts can be illustrated with careful planning, including: features, best practices, scenarios, product power (capabilities), ease-of-use, completed projects, end-user interaction, outputs, and development environments.



•

Become comfortable in the user interface quickly.

•

Work in a real project with no fear.

•

Add their own data/content (depending on the application).

•

Learn concepts more quickly.

•

Use a sample as a starting point for their project, rather than beginning from scratch. (People can be intimidated by “blank slates.”—Alan Cooper)

Project Planning When planning out your sample projects, keep the following in mind: 113

Writing and Communication

•

The data or content must yield meaningful results. If you want to demonstrate a number of features, make sure the sample has the appropriate amount of data or content.

•

Avoid proprietary content and graphics.

•

If you need a database, use one that is publicly available for download (if one of them fits your needs), if not, you may need to create one and make it available for download. Consider a web-based sample if setup will be too complex.

•

It is a good idea to establish themes for samples that you can use in other deliverables— for example, tutorials and training. The same data/content can be used across projects. This will provide a consistent experience for your customers, as well as save development time.

•

Downloading software and sample projects/ content should be as easy as possible.

•

If code snippets will be needed, make sure enough time is allotted to develop them.

•

Provide clear descriptions of the samples, as well as instructions for using them.

•

For desktop products, make sure there is a backup included, or way to restore the samples to their original state. One way to handle this is to include the samples in two directories in the installation.

•

Once samples are created, they need to be given visibility. There are a number of ways to do this. A few options: the product’s Getting Started Wizard, your website, the product interface, the online help/ documentation. You can publicize them via webcasts, email newsletters, blog posts and Tweets. After the initial rollout, you may want to ask your user community to contribute samples. Before the community is queried, the technology and guidelines for community samples will need to be developed by the team, and a plan put in place to encourage, recognize, and reward contributions. This may necessitate a new team member: the Community Manager.

Recommended Reading Cooper, Alan. About Face: The Essentials of User Interface Design, Wiley, 1995. Carliner, Saul. Informal Learning Basics, ASTD Press, 2012. Sierra, Kathy. Badass: Making Users Awesome, O’Reilly Media, 2015

Author Contact Information

Nicky Bleiel Watson Information Developer IBM 1710 Murray Avenue, Third Floor If developing a web-based sample, determine Pittsburgh, PA 15217 if a login will be needed and plan accordingly. +1.412.315.2148 Make sure the sample is tested on several browsers. Author Biography

Writing the Scripts Every sample should have a script or outline before sample creation begins. All objectives should be listed in the script so nothing is missed. When developing scripts, remember that scenarios should be realistic, and familiar to the audience. Make sure the content/data developed will work in your scenarios (for example, if your software creates charts, make sure the data will create charts that are meaningful). When illustrating best practices, make sure to highlight those in the sample. You can use video, audio, or any other relevant medium to augment your samples.

114

Distributing and Publicizing Samples

Nicky Bleiel is a Watson Information Developer at IBM. She is Immediate Past President of the Society for Technical Communication and has 20 years of experience writing and designing information for software products in a variety of industries. She is a popular speaker at many conferences, including the STC Summit, WritersUA, tcworld, CIDM (Content Management Strategies/DITA North America), and LavaCon; and has been published in STC’s Intercom, tcworld magazine, ISTC Communicator, and more. Learn more about her at www.nickybleiel.com. Follow her on Twitter @nickybleiel.

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 consistent—to build a community of happy users. Context—what one thing, physical or semantic, means in relation to another—shapes the outcome of a message. Text, in any context, affects user experience; organizations can test copy to improve usability and reach business goals. The design of communication bridges the art of exploration with the science of analyzing ourselves, our audience, the gaps between us, and how to evolve toward (and with) our audience.

Measure the Communicators

Document the Organization & Project An organization’s culture shapes the message produced, and the message style alters who connects with a brand, as well as how they engage. There is at least one person behind every brand’s message. Localized vocabularies appear based on geography, subject matter expertise, political beliefs, and other personal affiliations. A child learns labels and structures (“this is a bird”) from the people around them, but no child asks “is this a bird or a car” to distinguish the concepts.

Before an interaction begins, define yourself as an organization and who you want to become, as well as who your end user is and who they want to be next. A website is answering questions, such as “should I vote for this candidate,” “is this a brand I trust,” and “will I buy this widget.” The questions you lead users to answer—“why don’t I have the same widget as the Joneses?”—should prompt nodding heads and drive project goals.

Linguistic biases and blind spots can come from experience as well as ambition. A copywriter with a tight deadline could mistake structual familiarity with situational corectness, and a Millenial is more likely to consider “because” as sufficient to introduce a verb or noun than a Baby Boomer. And high school students who do not strongly identify with their hometown, and want to leave after graduation, are 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 in my kitchen or checking luggage at the airport, I have a fourth-grade reading level or a PhD in Top Quark Physics. Spatial boundaries and sociocultural connections change what communication is more effective in each interaction.

Consider the context and listen for the tone—vibrant, authoritative, curious, genuine—used by project owners as well as trusted assistants. Record this brand biography, and set a schedule to re-evaluate as you grow.

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 complete 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 grouped, both quantitative analytics and qualitative research will help determine user profiles or personas. Identify each category, their primary goal, and the main message for that user; rank the importance of 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 is the front page for someone.

as websites ask them to hold unfamiliar terms in working memory, instead of using elements that are “intuitive” according to a particular social group. “Meaning emerges at the confluence of a goal-directed actor-observer engaging with information directly in the environment,” according to Marsha Haverty.

Test for Surprises & Meaning

Language shapes the user experience. Words are the geometry of our human relationships: the depth of our past experiences translated through the breadth 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 Standardize course correction with scheduled reevaluation of your, and their importance to changing organizational goals.

Social gaps between an organization and a user can create understanding gaps through differences in vocabulary or semantic structure. After deciding how much we are willing to bend the message to reach desired users, the social difference between the speaker and listener can still potentially risk perceived brand sincerity. The message signal must be stronger than the contextual noise for recipients to receive the intended meaning. Information engagements must evolve to help users recognize the structure, coordinate their behavior to the structure, and maintain coupling through intermittent and evolving factors. Therefore, “tolerance for imprecision is a design value” when a meaning disconnect can interrupt or disrail an interaction. We increase the cognitive load of a web page by asking users to expend mental focus to find information or complete a task. User frustration increases 116

What people do, and how much, can reveal roadblocks between the speaker and listener. However, the measurements we track are data, which is not the same as information. Numbers only expose what people are currently doing with what they have already seen. The usefulness of quantitative tests depends on using (1) measurements of actual value, (2) an approach that translates inferences into observations, and (3) driving the quantitative research agenda wil qualitative finding. •

Reverse Card Sorting Categorization: Without seeing page content, can users correctly anticipate which page in a navigation structure would help them complete a provided task? If concepts are grouped with unexpected categories or labels, finding information and features can be frustrating to real users.

2015 STC Technical Communication Summit Proceedings



Clever Copy for Happy Users

•

Flesch Reading Ease Understandability: How many years of education does a user need to understand the text? A busy doctor can benefit from the same simplicity that reaches a patient, but the patient with a 6th grade education will not understand the full meaning articles with a 32.0 readability score.

•

Cloze Deletion Test Vocabulary: If one out of five words is removed from a passage, can the target audience correctly fill in the blanks? Look for patterns of missed words, and revisit terminology when there is more than a 30% failure rate.

•

A/B Testing Performance: If similar groups are presented alternate variations—of the copy or the interface delivering that copy—which variation performs better? The definition of “success” should be evaluated for more-insightful feedback (receiving more clicks does not mean receiving the right clicks).

•

Heatmapping Expectations: When presented with an interface, do user expectations of anticipated conventions match the expectations of the internal team? What seems obvious to a copywriter who sat through project meetings might not translate to users faced with a web page.

instead of a large and anonymous crowd, and consider if this message is worth their time.

Analyze with Qualitative Testing Discovering why something happens, and how to to fix problems, requires the open-ended questions of qualitative research. •

The Parking Lot Test Interesting: Would a person delay getting home from work to hear this message? Imagine three people in a parking lot,

•

The Mom Test Genuine: If your mother heard you say this, would she call shenanigans? Members of a language community notice outsiders wearing linguistic costumes, and making these gaps more obvious breeds distrust.

•

Five Second Test Actionable: When shown a screen for five seconds, what do they remember drawing their eye? The main call to action must be sufficiently obvious for people with the body of human knowledge at their fingertips, but limited time and attention.

•

Pair Storytelling Clear: Can a user easily summarize a passage of text? Patterns of missed or mistranslated meaning can be corrected. Start by describing a task with general language, and ask a user to talk through the rest of that task in their own words.

•

Day-After Recall Memorable: A day after reading a passage, can users remember the call to action? A simple hallway test can reveal if a message is “sticky” enough.

•

Usability Magnitude Estimation Functional: How difficult do users say a task was to complete? Average the difference between pre-task estimation and post-task assesment to separate usability flaws from marketing issues.

Build a Culture of Adaption Responding to insights requires an adaptive culture. It takes buy in from more than one person to turn testing results into messages that reach the intended audience with the intended meaning. Even freelanc-

Your Org End User

Who are you? Who are they?

Sets foundation

Want to be?

Marketing Opportunity

Want to be? Guides current tactics Guides ongoing strategy

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 shift observations into next steps.

Govern Communication Standards

a consistent, professional message. For entire organizations and specific projects, cross-functional teams can record and refer to the idiosyncrasies of subject-matter domain and marketing campaigns.

When you cannot use the standard terms of your team, clearly define descriptive and useful vocabContent governance is part policy and part proceulary in a glossary. Other team members may be dure, part strategy and part tactics. Be clear with highly educated in other areas, but if a “carousel” Plain Language, record and maintain a style guide matters to the content manager, the meaning of “carfor a project team to reference, rank content “chunks” ousel” will be important over the life of a project. on each screen, and regularly reevaluate standards.

Use a Plain Language Guidelines

Map Content Priority

Following the principles of Plain Language, copy can be easy to read, easy to use, and easy to understand the first time users encounter a text. The standard of being “plain” requires understanding, planning, and course correction, but it leads to clear meaning as well as actionable copy.

Ranking content is like the Highlander: “there can be only one” top priority. For each key page, group information and features into digestible segments such as a “buy now” button, a short list of related blog posts, or a paragraph summarizing features of a car. When designers are ready to move into wireframing, collaboration with content producers and managers can be part of the decision. Starting with a ranking of content helps designers across a range of desktop and mobile devices.

•

Speak to your audience.

•

Avoid jargon.

•

Give common words common meaning.

•

Know which grammar rules matter.

•

Be precise.

•

Promote descriptions, demote exceptions.

•

Don’t hind your verbs.

•

Be actionable.

•

Use visual aides.

For example, a website to sell widgets may rank “buy now” as top priority. The wireframe—a preliminary

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— can maintain a project-defined rank: 1. “Buy Now” button drive users to the online store. 2. Main menu to navigate site. 3. How our product will improve your life. 4. Store contact information. 5. Customize the widget options. 6. Customer testimonial. 7. Statement about brand’s superior quality.

Haverty, Marsha. “What We Mean by Meaning: New Structural Properties of IA.” Presentation at the Information Architecture Summit, Minneapolis, MN, April 22-26, 2015. Hay, Steph. “Being Real Builds Trust.” A List Apart (28 August 2012). http://alistapart.com/ article/being-real-builds-trust. Heath, Chip. Made to Stick: Why Some Ideas Survive and Others Die (New York, NY: Random House), 2007. Highlander. DVD. Directed by Russell (1986; Troy, MI Anchor Bay Entertainment, 2002). Hinton, Andrew. Understanding Context (Sebastopol, CA: O’Reilly Media, Inc.), 2015.

Whether on a desktop, a tablet, a smartphone, or a 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 Summit, Minneapolis, MN, April 22-26, Standardize Reevaluation 2015. Who is accountable for maintaining content standards, what is the definition of “successful” content within the project or organization, and what is the re-evaluation timetable? When everyone is responsible and every day is a reevaluation, no one will govern standards, at any time. Define the role, metrics, and schedule so that improving your best communication is built into every project.

References Colton, Lauren. “The Elegant Precision of Targeted, Actionable Language.” Presentation at ConveyUX, Seattle, WA, February 5, 2014. Colton, Lauren. “Mobile User Interface Design” in Professional Mobile Application Development (Indianapolis, IN: John Wiley & Sons, Inc., 2012), 89-115. Deutscher, Guy. Through the Language Glass: Why the World Looks Different in Other Languages (New York, NY: Metropolitan Books), 2010. “Federal Plain Language Guidelines.” plainlanguage. gov (1 March 2011). www.plainlanguage.gov/ howto/guidelines/FederalPLGuidelines/ FederalPLGuidelines.pdf. Garner, Bryan. HBR Guide to Better Business Writing (Boston, MA: Harvard Business School Publishing), 2012.

Wachter-Boettcher, Sarah. Content Everywhere: Strategy and Structure for Future-Ready Content (New York, NY: Rosenfeld Media), 2012. Welchman, Lisa. Managing Chaos: Digital Governance by Design (New York, NY: Rosenfeld Media), 2015. Wiebe, Joanna. CopyHackers Book 2: Formatting & the Essentials of Web Writing (Victoria, BC: Copyhackers), 2011. Wiebe, Joanna. CopyHackers Book 4: Buttons & Click-Worthy Calls to Action (Victoria, BC: Copyhackers), 2011. Zeratsky, John. “5 principles for great interface copywriting.” Google Ventures (18 February 2014). https://www.gv.com/lib/5-principlesfor-great-interface-copywriting.

Author Contact Information Lauren Colton Information Architect & Business Development Strategist Gravity Works Design & Development 1132 N. Washington Lansing, MI 48895 +1.517.481.2218

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 environments. 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.gravityworksdesign.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 architecture 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.

M

ost people face messes made of information (and people) everyday in their personal and/ or work lives. Whether you are a designer, a technologist or a businessperson, these messes stem from issues that are common regardless of the context for the communication at hand.

Everything Has Information Our world is a mess. Whether it be understanding your privacy rights on the latest social media channel, figuring out how to send your children to college and still retire on time, or re-launching your business to be more “digital”. There are a lot of hoops to jump through, all of which are a growing part of the human dilemma.

Since the mid nineties, pundits and thinkers have warned us about the tsunami of information1 that is headed our way. They spoke of it like an alien attack from afar, but this was a mess we were in the process of creating ourselves. If predictions are correct, we 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 with all this information coming our way. Because of this wave, there is a growing need regardless of your job or place in the world to be able to make sense of messes made of information.

121

Writing and Communication

Thinking about Information as a Material is Hard

Many people would take this bet. Why? Because everything they already know tells them that there were probably more cookies on that plate.

Information is one of the most profound concepts involved in being human. Our ability to perceive and communicate our meaning to each other is a basic complexity of our human minds that most people move through their lives not thinking too much about. Yet it drives us. Everything we do relies on this critical skill of communicating with one another.

The belief or non-belief that there were ever other cookies on that plate is the information each viewer interprets from the way the cookies were arranged. When we rearrange the cookies with the intent to change how people interpret them, we’re architecting information.

For simplicities’ sake it is often thought that information is all “things” that assist us with communication: text, pictures, and videos are the ready examples in today’s online world. It is also often misapprehended that information is anything that can be captured and filed away. But this isn’t quite useful in many cases as it misses the most important aspect of information, which is perception. From the standpoint of materiality, information can be looked at as the subjective result of the content the user perceives based on their context.

While some users might consider it a fact that there were other cookies on that plate at some point, others may disagree because they never saw it with their own eyes. While some users might consider it a fact that this arrangement of cookies means the chocolate chip cookie is more popular, other users might smell the oatmeal raisin wafting in the air and believe that the chocolate chip cookie is not more popular, but instead older than the oatmeal raisin cookies. While we can arrange things with the intent to communicate certain information, we can’t actually make information. Our users do that for us.

Information vs. Data vs. Content. The content that you provide and the information a user perceives can be slightly (or drastically) different. The synonymous use of the words data, content and information doesn’t encourage those who make content or those who collect data to consider the implications of connotation. Instead the makers of content focus solely on the denotation at the detriment of clarity. While the differences may be slight between these three basic terms, they are important: •

Data. The individual pieces of context, knowledge, assumptions and questions each viewer considers to come to a conclusion regarding the world around them.

•

Content. Whatever a user is interacting with, or as a maker, whatever you’re arranging or sequencing.

•

Information. Each user’s unique interpretation from the arrangement or sequence of content that they encounter.

For example, imagine you’re looking into a bakery 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

There is No Truth. Only Spin Once you remove the consistency between information and content, many people’s anxiety is increased significantly. It turns out that when admitting to that level of subjectivity, we are also being asked to give up on concepts like “right and wrong” and “good and bad”. We are faced with the idea that all information inherently has spin, because all information went through the hands and minds of at least one other person on its way into our mind.

We Make and Use Things within a Nested Set of Structures Another complexity to this admission of subjectivity is the multitude of intertwingled2 connections that the things we make have to other things. These levels have different complexities, considerations and often are guided by different teams. Reconciling and connecting the dots between these levels is often the only way to truly make sense of a mess without just adding another wrinkle to an already complex ecosystem.

2015 STC Technical Communication Summit Proceedings



How to Make Sense of Any Mess

The following is a taxonomy for understanding the nested levels of place: •

Object. a specific thing.

•

Interface. a point where a user affects that thing.

•

Location. a particular place or position.

•

Journey. the steps in or between locations.

•

Structure. a configuration of objects and locations.

Objects Allow Us to Compare Our Mental Models You can see people using their hands more in conversations as the complexity of the topic gets too much for their words alone. When we set out a piece of paper between us and use it to visualize a shared model we can get much closer to our goal: agreement.

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 insights. When we reference objects during a conver• Ecosystem. a collection of related systems. sation, we can go deeper and be more specific than Changes that happen at one of these levels can drasverbalizing 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 picreact 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 Always Politics Involved in Making Sense Whether you are working on a small team or are deeply embedded in a large one, politics is a part of how we will arrange things to make sense to our audience. Everyone has an opinion, because everyone has their own map of the way things work. That map is called their mental model and it influences their reaction to everything. Even while you are reading this paper, your mental model is being referenced and perhaps slightly altered according to how you are perceiving what you are reading. Since everyone has there own model of the way things work, working together can be fraught with difficulty, especially when the subject is too complex to easily grasp or there are many different paths or options. It should be expected that we will have to work through these opinions, no matter how political a battle ahead, because without basic agreement, our mess will never make sense.

There are plenty of reasons to not make sense of whatever mess you might be facing. Maybe it is “above your pay grade” or “can’t be fixed in the time you have.” That’s fine, as long as you understand that the nature of messes is to grow when not tended to. Ways people ignore or hide the mess: •

Fluff the visuals. Make it prettier and perhaps maybe no one will notice the mess.

•

Explain the Mess. Signage, tutorials, and apologetic toned emails are ways to explain the mess to users

•

Incentivize Dealing with Messes. Charging for a clearer solution, giving discounts to legacy users

No matter what your excuse or alleviation mechanism, the mess will still be there when you get around to it.

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, Dan Klyn of The Understanding Group proposed three critical components3 to be considered in information architecture.

define a word with the variation of that same word. •

Remember language is not just words. Icons, pictures, sounds, light, and even smells can be the language that is most effective in reaching our intent. While words are not the only thing we need to be concerned with in understand our language, we must also remember that people often make up words for things that don’t have labels yet. This is called an uncontrolled vocabulary.

•

Watch out for linguistic insecurity. This is the all too common feeling of language being in the way of communicating effectively with someone. Whether it is a colleague talking in jargon or an interface using overly technical speak, there are examples of experiencing linguistic insecurity in everyone’s life. The important part is to remember how that feels and not make your users, clients or co workers ever feel like that. This is important because people experiencing linguistic insecurity are often difficult to communicate with.

These three components are best thought of as nested inside one another like those Russian dolls of subsequently smaller stature. •

Ontology. What do we mean when we say what we say?

•

Taxonomy. What structures do we provide to make sure that meaning is found?

•

Choreography. How should language and structure change across channels and contexts to uphold the integrity of the intended meaning?

Ontology The thing that’s most difficult about working with other people is that language is merely short hand for what we actually mean. Therefore many words and phrases can mean roughly the same thing. For example, on an interface design the word “add” and “upload” could mean roughly the same thing. But the choice of which one to use is incredibly important. It may feel odd to ask a user to “Upload Blog Post”, because they will be merely typing words into a box and clicking an action to make it available publicly. In this case “Add Blog Post” probably feels more right. Why? Because that choice helps users understand what they will be asked to do next. Our choice of language can drastically impact the thing we make, yet all too often language is painted on after the fact. Ontology is the study of meaning. It involves looking deeply at what we mean and deciding that language would be best used to convey that to our users. To assure that your ontology is clear, consider the following tools: •

•

124

Create a controlled vocabulary. A controlled vocabulary is an agreed to documentation of language within a context of use. These are useful to think of both in terms of words you say and words you don’t say. Define nested terms. Often there are terms within the definition of a term that actually need to be further defined for true clarity to be reached. Remember, never

Taxonomy There are two inseparable parts to everything we interact with: content and structure. One without the other is useless. Imagine if I were to rip all the words out of your favorite book and dump them into a pile on the floor. We can all agree this is no where near usable or transferable to another person as your favorite book. This is because the structure we give to this content is what makes is the book you love. The structure that we put our content in can drastically affect the way people perceive our content. This also changes how we use the content that is provided. For example: you would never take a spoon from the “dirty spoons” bin in a cafe because of the effective taxonomy of this environment. Imagine trying to figure out which spoons are clean and which are dirty without the labels. It is perhaps most important to remember that judgment is inherent in the ways that we group and label things into systems for others to understand. The following are some lessons for assuring you are thinking about the taxonomy of what you are offering.

2015 STC Technical Communication Summit Proceedings



How to Make Sense of Any Mess

•

LATCH4. According to Richard Saul Wurman, there are only five ways to organize anything (Location, Alphabetical, Time, Category and Hierarchy. This may seem simple, but none of these is ever a “sure thing”—instead each has its own complexities and contexts of uselessness. Imagine a phone book arranged by birthdate (time), or a grocery store arranged alphabetically by main ingredient.

•

Facets. A facet is a individual piece of knowledge that we understand about something, for example the season in which a certain type of vegetable is grown during is a facet we might call “Season”, we may also be able to know that vegetable’s color, classification, scientific name etc. Facets are the way we individualize a taxonomy to be appropriate to the content being arranged.

•

Connotation vs. Denotation. Sometimes how something is exactly defined doesn’t matter as much as what something means to someone else. For example: tomatoes and many other types of produce are often “misclassified” on grocery store websites as vegetables. This isn’t because the designers of these sites are naïve to scientific taxonomic standards; instead it is likely because they understand that in their user’s mental model tomatoes are treated more like vegetables than like fruit.

Choreography The way that a choreographer thinks about a dance is different than the way a dancer experiences it. One impacts the other, but they would never be mistaken for one another. Similarly, the way a information architecture is choreographed is different that the way a user experiences it. But it is the choice of available moves that is important in order for the dancer to have the direction they need to get through the performance. When we talk about choreographing information architectures, we are speaking to the idea that any system of language that we might lay out has to be flexible enough for many instances of use across channels and contexts. Channels are the mediums for communication that we use to pass information around. For example: A broadcast TV commercial, bus shelter ad and a

website may be created for a single campaign for a single organization, yet each piece of content exists on its own channel. Context is the larger circumstance surrounding the moment of use. For example: A user seeing our bus shelter ad and accessing our website via their mobile device is a different context of use than a user typing in our URL via their desktop computer, or calling our 1800 number. In the world of physical architecture, we choreograph the movement of users through physical space by using cues that tell them what we intend for them to do there. They therefore know hallways are for transportation and rooms are for pausing around activity. Similarly, the content and structure of each room indicates the intended use of that space. Think about how many elements you would have to remove from a kitchen before a user would no longer know it was a kitchen just by entering it. This concept of deciding how a space is arranged to communicate an intended use is called placemaking. This practice is important to understand, not just in physical places. Digital places also need to be arranged in a way that communicates intent to the users of it. A good example of purposeful choreography in digital placemaking would be the fact that one cannot upload a picture to instagram.com nor edit a Medium.com article from a mobile device. It 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 users ought not to use their products in these ways, as it would call their product’s intent into question. A product lacking basic desktop or mobile consistency could get railed in a heuristic review of those products, should the reviewer not take into account the intent of the makers. A user researcher could easily raise these as “things users keep asking for” in both cases, but that too does not matter as much as what it would mean if these slips in the integrity of meaning were to take place. Would Instagram be instant if you could upload from your desktop? Would it open the flood gate of other features like albums turning it into something more resembling Flickr? Would Medium articles be as profoundly thoughtful if people were allowed to type them with their thumbs on-the-go? Would it just be another blog-

2015 STC Technical Communication Summit Proceedings

125

Writing and Communication

ging platform based on that one tiny choreographic adjustment? In cases like this, asking the question is as important as the ability to find an answer.

Conclusion In conclusion, information architecture is all around us. It is baked into everything that we experience and a huge factor in the success of everything we as makers bring to the world around us. Information architecture always exists; it isn’t something you get to choose your way out of. Information architecture is not only for information architects to think about and improve upon. We are all making this mess together, and it is going to take all of us to make sense of it.

Author Biography Abby Covert is an independent information architect in New York City. She specializes in delivering a collaborative information architecture process and teaching those that she works with along the way. She speaks and writes under the pseudonym Abby the IA, focusing on sharing information architecture content with those working within the design and technology communities. She is the author of “How to Make Sense of Any Mess” a book about information architecture for everybody. She teaches information architecture at The School of Visual Arts. She is also the current president of the Information Architecture Institute, a global nonprofit membership organization focused on empowering IA leadership, currently serving members in 73 countries.

If you make anything, you are already practicing information architecture. Now that you have the baseline knowledge to think about IA more specifically, 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 Wurman, Richard Saul. Information Architects (Graphis Inc., 1997)

1

Nelson, Ted. Computer Lib/Deam Machines (Nelson, 1974)

2

Klyn, Dan. Understanding Information Architecture (TUG, 2014)

3

Wurman, Richard Saul. Information Anxiety (Truong, 1989)

4

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 standards; these are some of the challenges you may face when preparing your product documentation. 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? A global audit is the process of identifying all content that is not appropriate for I18N (internationalization) or ready for L10N (localization): •

•

improving internal processes that lead to problems during L10N

TC to the Rescue!

Why does this matter? Content that is not globI18N means creating a product (and its docal-ready can mean product failure in some markets. umentation) that is as acceptable as possible During L10N, it can mean longer, costlier translation to as wide an audience as possible, using and even embarrassing mistakes! neutral examples and controlled English (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 modpotentially 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 underfrom I18N sources. stand our products and their domains. We are also

A global audit is simply an internal review of your existing documentation content, including:



•

•

identifying potential problems

•

correcting them

•

establishing improved standards (for example, making changes to your in-house style guide) to prevent the problems in the future

the in-house linguistic experts. Therefore, we are logically the right people to spearhead the effort to make our content global-ready. We are also the correct point of contact with the L10N agencies.

127

Writing and Communication

How Do You Do a Global Audit?

interactions may be confusing (or downright annoying) in print. Remember, humor never translates well!

Start by reviewing your existing content, looking for the following things: 1. Review the writing. Look for idiom, local expressions, and slang. I call this “we-centric” writing. Remember that what is clear to you may not be clear to someone who is not a native speaker. Look for long sentences and complex structure (such as nested clauses). Ideally, keep sentences under 13 words. Look for words being used in different ways (a classic problem in English). For example, “Hose down the sidewalk with the hose” relies too heavily on context and is difficult to understand and translate. Look for inconsistencies in terminology (product and feature names, technical terms, interface elements, and the verbs for user actions). Inconsistency is one of the biggest culprits for adding complexity and cost to L10N projects. 2. Review global standards. Look for units of measurement. Make sure that you are using metric values. If necessary, you can list Imperial values parenthetically. Look at date and time formats. Americans are unique in listing month before date, leaving dangerous ambiguity with number-only dates. For example, most people outside of North America will interpret “11/08/15” the 11th of August. To avoid ambiguity, use a modified ISO format (“08 November 2015”). And think of that casual reference to “8:00 pm ET” on your website; it is utterly confusing to users outside of North America. Instead, use a 24-hour time (thus getting rid of the confusing am/pm issue) and use a globally-recognized point of reference, such as UTC (for example, “20:00 UTC -4”). Look for lack of parity with place names. For example, I once had a client who had the following as part of a use case: “Tony lives in Los Angeles, California, and Michelle lives in Paris, France.” He didn’t understand why this was so jolting and offensive to his users outside of the US. 3. Review the examples. If you have examples in your documentation, make sure that they are as “vanilla” (that is, bland and generic) as possible. Avoid cultural references that would only make sense to someone from your area. Above all, avoid humor. What can be acceptable in face-to-face 128

4. Review the graphics. Make sure that the images you use are not problematic. Seemingly innocent hand gestures in one culture can be obscene in another. And those icons that make sense to you may be a broken metaphor in another country. Look at the graphics themselves and make sure that the text is always a separate layer in the DTP tool, not inside the graphic. 5. Review the tool usage. L10N projects are often bogged down because the source content is so sloppy. Illegal and local formatting, manual “tweaking” of content to force pages to fit, and other layout sins lead to expensive and time-consuming DTP fixes by the L10N agency. Remember that language bloat will cause translated content to expand by as much as 40%. Layout and design can be problematic if you didn’t take into consideration what will happen if your content is translated to RTL (right-to-left) languages.

How Do You Use the Audit Results? Once you have reviewed your existing content for those five general areas, you can start to apply the results: 1. Fix the writing problems. Obviously, the problems that you found have to be fixed. But more than that, you have to update your in-house style guide to reflect the new global awareness. Take it a step further and develop training for the other writers and editors on your team. 2. Find a reputable L10N resource. If your company is not already localizing, you’ll need to help find the right L10N agency. Look for translators who are mother-tongue in the target languages and have some experience in your domain. (For example, someone who is a skilled translator of children’s literature is not necessarily the right person to translate a medical device manual!) Get references. Give them a short sample to translate and then give the results to your company’s rep in the target location. 3. Do usability testing. To make sure that you have hit the target for I18N, find testers 2015 STC Technical Communication Summit Proceedings



Performing a Global Audit

who match your personas but are not native speakers. Put them through basic usability testing with the documentation, picking a few key procedures or some more difficult conceptual topics. Have them read sections out loud. Ask them to explain back to you in their own words. Look for anything you may have overlooked that is “we-centric” writing. 4. Develop in-house support. Some people may not understand what you are trying to do. Ultimately, you will not be able to make content more global-ready if you do not cultivate support from other stakeholders. Therefore, take the time to do your research. Figure out what their pain points are and explain how your global audit can help those specific issues. For example, not everyone cares about good writing or the user experience! The regulatory person may care only about compliance, while a product manager may be more concerned about TTM (time to market). You have to be able to explain how global-ready content helps them. 5. Start with a simple goal. Don’t try to do everything. Start with a small project. Tackle a few simple things, such as terminology and global notation. Get input from R&D and Marketing so that the terms can be agreed on 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.

Resources Kohl, John R. The Global English Style Guide: Writing Clear, Translatable Documentation for a Global Market (Cary, NC: SAS Institute Inc.), 2008.

Author Contact Information Leah Guren Owner Cow TC Karmiel, Israel www.cowtc.com +972.544.853.473

Author Biography Leah Guren is the owner/operator of Cow TC. She has been active in the field of technical communication since 1980 as a writer, manager, Help author, and consultant. She now devotes her time to usability consulting and TC training, primarily in Israel and Europe. Leah also teaches several certificate courses for STC and is a popular speaker at various TC-related conferences around the world. Her clients are some of the top hi-tech companies internationally, including Intel, IBM, and Microsoft. Leah is an STC Fellow.

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 easily 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 element 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, traditional 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

A

n important first step in creating a strategy is implementing a meaningful discovery process. This means engaging more than just your external users; your internal stakeholders are equally important. Once you’ve identified all stakeholders, learn the specific content needs of each. How you go about this will vary. For external users, try working with the design or user experience teams in your company. If these positions do not exist, support is also a good option. You need to work with individuals who regularly interact with clients be it answering their questions, trying to understand their needs, or solving their problems. Ideally, through interactions with one of these groups, you arrange your own contact with the external users. For example, approach the UX group to help you setup a “discovery” process that allows you to test various iterations of your content—embedded help vs. web-based help systems, training videos vs. training documentation.

The granularity of your test is also very important. For example, if you discover users prefer embedded help be prepared to then provide them a couple of different embedded help options or if you discover training videos more popular than the written instructions, be prepared to provide a couple different video styles—maybe one more interactive then the other. The best way to approach this is to plan for different stages in the discovery process, with the first stage focusing on the delivery medium and the second and maybe third focusing on the different style options available in the selected medium. Your goal in this process—become fluent with the users’ general business operations to better satisfy their user assistance needs. Learning the needs of your internal users should be easier. Simply reach out and talk to any potential internal user of your content. This step also involves learning who are your internal stakeholders? The most common answers to this question are marketing, support, and training, but to be thorough, spend some time investigating your corporate structure to

131

Writing and Communication

make sure you’re not overlooking any other groups that may benefit from the content you create. The general advantages to a cross-discipline approach are reduced duplication of effort, shared information, and leveraged expertise. Why have training and documentation create the same content? A successful content strategy understands and incorporates the training team’s needs. Sophisticated authoring tools make it easy to create and share content that satisfies the needs of both disciplines. The same is true with the knowledge base articles typically created by support teams. Often times overtaxed support teams cut and paste this content from the documentation set. Even worse, once created, these articles are often overlooked and not updated. Also, why struggle as a writer trying to created high-quality graphics for your visual deliverables. Work with marketing. Not only may they be able to help you with graphics, they can probably also help promote your various help deliverables—another important consideration in any content strategy.

Deliverables

content, and define each piece. You also must detail reuse/sharing strategies, best practices/workflows, formatting, styles and tone. All require a good deal of research and testing.

Tools Next, determine how you plan to create these deliverables. This step involves investigating and pricing tool sets that will allow you to create included deliverables and support your information architecture. In this step you probably also want to consider your current talent pool. For example, if your current pool of writers lack advanced technical skills you may want to avoid more advanced/complicated tool sets. Your talent pool will also play a role in determining deliverables, unless of course you can leverage the talents of other departments. Pricing plays a huge role in determining tools. Make sure to win corporate approval for tools and pricing before including them in your strategy. Finally, create a governing method. You need to put a process in place that makes sure the rules and process detailed in the strategy are followed. Important governance considerations are who is responsible, what are their powers/responsibilities, and how strictly do they enforce. It is also helpful to define reporting and workflows for this process.

Once you identify all your users and their content needs, you next need to determine your deliverables. If you’ve done a good job identifying your users and their needs, determining your deliverables should be easy. Common deliverables include traditional documentation, help files, videos, video tutorials, and visual aids such as walk throughs or information graphics. Try to include and test all options with your users during the discovery process and you should come away from discovery knowing exactly what deliverables you want to provide. The key to success with deliverables is not to include something because it is new and “cool.” It must satisfy a need identified during discovering.

As outlined in this article, creating a content strategy is not simple; it involves a great deal of testing and research. However, if done correctly, one piece of the strategy puzzle leads nicely into the next, and it all starts with understanding your users—both external and internal—and working to satisfy their needs.

Architecture

Author Contact Information

Also, keeping in mind the needs of all identified users, determine your content’s architecture: topic-based, book metaphor, something else? If you need to satisfy a variety of output types and formats—for example repurpose your help content 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 information types, such as concept, task, and reference 132

Conclusion

Denise Kadilak Information Architect/Team Manager Blackbaud 1020 Auburn Ave. Cleveland, OH 44113 +1.216.251.0716

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 workflows 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 responsibilities as well as the need for some specialized techniques.

Hardware Technical Writing Types

Operator

H

Operator manuals are the most common type of hardware writing. The organization, principles, and level of expected audience understanding is essentially the same as in software manuals.

ardware technical documentation is oriented around either doing something with the subject, or doing something to it. Operators will work with the subject, field service/repair personnel will do things to it. As a result, most hardware technical documentation falls into one of these four categories:



•

Operator level documentation

•

Maintenance manuals and documentation

•

Manufacturing Instructions

•

Parts catalogues

Maintenance Maintenance manuals are aimed at more experienced users, and typically they are repair technicians tasked to do physical work on the systems. Frequently this work must be done at customer sites 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 be less than ideal. Maintenance manuals are categorized by the level of complexity in the repairs, which in turn are defined by the level of repair the user is permitted to perform. The three basic types of manuals are Field level, Intermediate level, and Factory or Depot level. •

•

•

Field level manuals include only the simplest and most basic repairs to a unit, using a minimal amount of tools. Typical operations are the removal of faulty components (“Field Replaceable Units” or FRUs) and installation of replacements. Field level manuals typically also include preventive maintenance, which is a set of regularly scheduled tasks (for example fluid replacement) designed to keep the equipment operating properly. Intermediate level manuals are aimed at more experienced technicians and include more significant repair techniques. They include more extensive disassembly and system replacement tasks, as well as more detailed troubleshooting techniques. Intermediate level manuals typically include wiring or other system schematics, the user’s tool set devices such as digital multimeters, torque wrenches, or boroscopes. Of the three types of maintenance manuals, the intermediate manuals tend to contain the most complex procedural instructions. Factory or Depot level manuals are used when extensive rework or repair is needed. These tasks can include complete rewiring, fabrication of new parts, machining/grinding operations, and welding. Although the level of task is deeper, in many cases these manuals do not contain detailed step-by-step operations because the user is expected to have knowledge and experience in the use of the tools needed. For example, the instruction 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.

Hardware manufacturing companies that want to achieve or maintain ISO certification struggle with the problem of ensuring that hardware is built to specific quality standards, that every component is built the same way every time no matter which technician performs the assembly. Companies achieve this goal by requiring the technicians follow approved written procedures. Manufacturing instructions have to be written down to the most basic level, must be explain the entire assembly or manufacturing process, and must be detailed to a level that ensures a consistent and repeatable process. Manufacturing instructions also normally include complete lists of all the parts, all the consumables (lubricants, coatings, adhesives), and all the expendables (clips, safety wire) used in the process of assembling the product. As a result, the manufacturing instructions often are some of the largest documentation sets for the product. For example, a microwave-oven sized DNA analyzer currently in production by one company has an operator manual with a length of about 35 pages, but the manufacturing instructions total about 800 pages. Or, in aerospace, a set of maintenance manuals for a typical airliner may occupy 15 or 20 meters of shelf space but it’s not unusual for the manufacturing instructions (if printed) to exceed the weight of the completed aircraft.

Parts Catalogues Parts catalogues can be used at any level of operation or maintenance, and often include a complete and illustrated list of every component in the hardware system. They are used to order specific replacement parts for the system. Parts catalogues are often called by different names, depending on the standard or practice of the manufacturer, operator, or both. Common names include “Illustrated Parts Breakdown” and “Repair Parts List.”

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



Safety Always Users of hardware manuals may be dealing with a series of potential health hazards including high voltage, moving parts, sharp edges, radiation, heat, fumes, loud noises, confined space, and altitude. Users must be warned of the hazard, the potential consequence, and ways to avoid the hazard.

Hardware Writing: You Can’t Always Touch It

ernment agency, contractor requirements, or other company policy. For example:

ANSI Z535.6 describes one of several types of safety admonition systems in common use. The style and format of an admonition system may be dictated by contractual requirements. For example, US DoD systems normally are required to follow the system detailed in MIL-STD-38784. Commercial aerospace The importance of including adequate safety information cannot be stressed enough. As an example, the two worst aviation disasters in US history (at the time of this writing) were traced back to relatively minor errors in the technical documentation. The two accidents total more than 500 lost lives.

•

Documents for US Department of Defense contracts may be required to adhere to MIL-STD-38784

•

Commercial aerospace documents may be required to adhere to ATA 100 or iSpec 2200

•

Contractual requirements may dictate adherence to ISO 29845:2011 or the 01.110 series

•

Automotive documentation may be required to follow SAE standards

While the specifications differ in detail, the purpose of each is to provide a common look and feel for documentation covering specific product or industry areas. In a bit of good news for technical communicators, frequently these specifications already exist in in electronic formats that play well with XML driven publishing systems.

Useful Skills •

Ability to read engineering drawings.

Standards and Specifications

•

Hardware documentation format and layout may be controlled by specifications set out either by a gov-

Familiarity with shop tools or machine processes.

•

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 Illustrations in hardware documentation can convey a wide variety of details, including shape, controls, individual parts, and areas of movement. Once requiring the talents of a skilled artist, today technical communicators can produce complex and detailed illustrations using common graphics tools. In addition to traditional tools such as Photoshop or Adobe Illustrator, hardware design tools such as Solidworks can be paired with specialized graphics tools that allow the creation of figures directly from the solid model. Different styles of illustrations serve different purposes. In the examples shown below, the exploded view is best for showing all of the components in the device, the ghost view is best for showing the relative position of a subsystem in the device.

Future Trends Hardware documentation is the oldest form of technical communication, the earliest known examples are on clay tablets. As communication technology has changed, so has the method of delivery. For example: •

Video is becoming more popular as a method of delivery. A well-produced video can provide a better explanation than pages of text. While video presentations are becoming

more common, many suffer from hasty production and are of poor quality. A properly prepared instructional video requires at least an hour of preparation time for each minute of video time, it should be scripted in advance, well-lit, and planned. •

Mobile devices can be used as aids in documentation in ways that go beyond just converting standard documentation to a mobile format. For example, some Audi automobiles in Europe feature an owner’s manual coupled with an iPhone, the owner aims the iPhone camera at a part of the car and the device automatically pulls up the data in active video form.

•

Augmented reality systems are already in use in manufacturing. For example, Lockheed Martin workers assembling some components of the F-35 Lightning II fighter airplane use the Epson Moverio BT-200 system to display all of the assembly information required. The technical documentation is displayed as graphics and text seemingly in front of the user.

Conclusion Although sometimes given less respect than software documentation over the past few decades, hardware documentation has a long history in technical communication and will continue to be an important

Figure 3. Epson Movario BT-200 138

2015 STC Technical Communication Summit Proceedings



part of the profession. Hardware developments are the cutting edge of technology, and constant change in hardware development means constant change in the documentation. The specialty of hardware documentation can be challenging and exciting…and, sometimes after all, you really can touch it.

Resources American National Standards Institute “ANSI Z535.6 American National Standard for Product Safety Information in Product Manuals, Instructions, and Other Collateral Materials.” http://www.nema.org/standards/z535/ pages/default.aspx

Hardware Writing: You Can’t Always Touch It

X-ray systems, and DNA analysis devices. Rick has a Bachelor of Science in Journalism from Ohio University in Athens OH, and Master of Science in Technical Writing from Rensselaer Polytechnic Institute in Troy, NY. Born and raised in New Jersey, Rick has been living in the northern metropolitan area of Boston MA since 1990. Rick’s hobbies include martial arts and scale model aircraft construction, his favorite subjects in the latter being the same aircraft that he has written about. Rick is also the author of the Squadron/Signal book C-5 Galaxy in Action, a history of the development and operational history of the largest airplane in the US Air Force inventory.

International Standards Organization, “ISO 38641:2011, Graphical symbols—Safety Colours and Safety Signs—Part 1: Design Principles for Safety signs and Safety Markings.” Acquisition Community Connection, “MILSTD-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 procedures. Rick is a past president of the STC Boston and New England chapters, and has also served as chapter Secretary, Treasurer, and social media manager. 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 messaging 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 procedures, and enforcing that process is your job. How do you incorporate what’s really happening at your company into the process?

K

nowing when you may be flexible in the process and when you should not can help you publish this information in a timely and correct manner.

Policy Violations You might work with a committee to review and update the employee handbook, which contains Human Resources’ and safety policies. If you are aware that managers and employees violate certain policies consistently, revise those policies with the following points in mind:

Record the policy changes in the document history.

•

Update the document’s revised date and approver name.

Prioritization Some documents are very important and must be approved out of cycle. You can move them forward by being persistent: •

Send documents out of cycle rarely; avoid sending weekly if your approval cycle is monthly.

•

Set a shorter response time for out-of-cycle approvals.

•

Remove unnecessary words and what if scenarios.

•

Re-write the policy in Plain English.

•

Use active voice.

•

•

Emphasize what employees should do, rather than what they should not.

Send a reminder to or call outstanding approvers shortly before the deadline.

•

Use follow-up flags to remind yourself and the approvers about deadlines.

•

Know which approvers you can pester. For those you should not pester, ask the policy submitter to help with reminders.

Handling Approved Documents There will be some policies that are not approved in your usual way. For example, policies about company governance are often reviewed by subject matter experts at the C level and approved by the Board of Directors. Work with these policies as follows:



•

•

Apply the correct template and document styles.

•

Perform an abbreviated copy edit, checking for proper usage and grammar and the correct use of certain terms only.

You might also work with people who want you to hurry, but then make you wait. Remember those people well and document their projects well. Handle future requests with care so that they do not disrupt other high-priority projects.

141

Writing and Communication

Review Quality Too often, reviewers do not take their responsibilities 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 participate 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 previously the Policies & Procedures Coordinator and was responsible for writing, editing, facilitating reviews and approvals, and publishing policies and procedures. 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.

T

echnical communicators can enhance the mobile user experience with a strategy that maximizes mobile content delivery. This workshop shares best practices for producing effective content to enhance the mobile user experience. First, we’ll share our tips and strategies for producing effective content. Then you’ll put them into practice by producing your own mobile messages, product tours, and notifications.

Explosive Growth of Mobile and Wearables The rapid proliferation of mobile and wearable devices brings opportunities for technical communicators who create content and user assistance. Mobile devices and apps are enjoying explosive growth: •

1B smartphones shipped in 2014 (IDC)

•

More than 1B Android devices have been sold, and we check them 100B times per day. (The Verge)

•

The Apple app store posted 1.2M apps and 75M downloads in 2014. (Tech Crunch)

Wearable technology has been called Mobile 2.0, and the wearables market is also growing quickly.



•

Wearable market growth is predicted to expand from $10M in 2014 to $300M in 2018. (Business Insider)

•

In 2014, 27% of developers surveyed said they plan to create apps for wearables. (Strategy Analytics)

With such dramatic growth, it‘s more important than ever to provide mobile and wearable content that meets users’ needs.

What is Mobile Content? Mobile content includes all of the text on mobile screens, including tours, messages, notifications, and tips. When you are working on mobile projects, you may also work on auxiliary content, such as: •

App store descriptions of features and updates

•

Getting started, tips, and tricks

•

Help topics, FAQs, and communities

You may also be asked to host an end-user license agreement (EULA) as a web page and provide your development team with a link to the content for apps and app stores.

Prototypes Help You Create Effective Mobile Content When developing mobile content, using prototypes is indispensable. Mobile prototypes identify issues and requirements early, while you still have time to adapt the content. Prototyping can help with: •

Buy-in 143

Writing and Communication

•

Requirements

•

Feedback

•

Scheduling

•

Quality

•

Profit

double-touch, drag, swipe, pinch, and spread. Review operating system guidelines for the mobile device you are documenting to ensure that you use the correct term. Mobile message best practices:

Prototypes can range from low-fidelity, such as a sketch on paper, to high-fidelity screens that closely resemble the actual user interface. Consider starting with low-fidelity prototypes, which are easier and cheaper to produce, to get early feedback. Then progress to increasingly high-fidelity prototypes for usability tests. Prototypes, listed from low to high fidelity:

•

Use a friendly, informal tone

•

Be brief

•

Use simple, clear language

•

Give a positive message without blaming the user

•

Use the correct touch terminology for the operating system

•

Give information to help users decide between options

•

Sketches

•

Templates

•

Integrate with design

•

Stencils

•

Design for delight

•

Presentation software

•

HTML pages in mobile browsers

What to avoid in mobile messages:

Prototyping Exercises This workshop provides three exercises for prototyping mobile and wearable content. We’ll do one exercise during the workshop. You can complete the other two exercises anytime.

•

Complexity

•

Lengthiness

•

Formality

•

Mimicking desktop text

Scenario

Exercise 1—Mobile Messages 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.

Your product manager wants to add a feature for password reset. You are asked to mock up messages for the screen. You must present this to your team to get buy-in.

Mobile content must use the correct “touch” terminology, such as: touch, press, long press, tap,

Figure 1. Example—Touch Terminology 144

Figure 2. Example—Password Reset 2015 STC Technical Communication Summit Proceedings



Don’t Just Shrink It; Rethink It!

•

Instructions In the next 15 minutes, design messages to reset a mobile user’s password. 1. Join a small group. 2. Discuss and plan your strategy. 3. Design and sketch.

Complexity

Scenario Your product manager shares product features for a tour for a cloud drive app. You are asked to mock up content. You must present it to your team to get buy-in. Features from your PM:

4. Pick a spokesperson.

•

You can save all types of files on the cloud drive

Your Turn

•

Share the content of your messages with other workshop participants.

You can access your files from anywhere, anytime, from any device

•

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 details for the app. Tours can give brief highlights of key features, introduce goals, and point out interactions.

In the next 15 minutes, prototype a tour that highlights features for a cloud drive app: 1. Join a small group. 2. Discuss and plan your strategy.

Best practices: •

Be brief

•

Be helpful

•

Be engaging

•

Highlight key features

•

Show key actions

•

Integrate with design

3. Design and sketch. 4. Pick a spokesperson.

Your Turn Share the content of your tour and show how it points out the key points from your product 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 for Wearable Apps A special consideration for wearable technology is that people can wear devices all day. This makes it especially important to economize on content. Wearable notifications should be useful and provide needed information at the right time and place. They should not annoy users as they go about their daily activities. Notifications should provide what users want or need, when they need it, on the device of their choosing.

More detail is provided in Marta Rauch’s STC Intercom article and Summit presentation on wearable technology: •

http://intercom.stc.org/2014/04/wearabletechnology-and-google-glass-why-it-matters/

•

http://summit.stc.org/responsive/summit2014.htm#!Documents/wearabletechnologyandgoogleglasswhyitmatters.htm

Scenario

•

What is the primary purpose of this screen?

Your team is designing a fitness app with a smartwatch interface. You are asked to prototype a fitness notification for the wearable device. You must present 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://rachelhinman.com/)

In the next 15 minutes, prototype the interface for the wearable’s fitness app:

Edit especially ruthlessly for wearable content. As you write and edit, ask:

•

Notifications for wearables should be: •

Useful

•

Timely

•

Unobtrusive

•

Relevant

•

Concise

•

Straightforward

•

Visual

•

Adaptable

•

Accessible

1. Join a small group. 2. Discuss and plan your strategy. 3. Design and sketch. 4. Pick a spokesperson.

Your Turn Share the content of your notification.

Figure 6. Example—Wearable Fitness Notification

Conclusion

Figure 5. Example—Useful, Timely, Relevant, Concise, Straightforward, Visual 146

Mobile and wearable devices have unique requirements for useful content. To ensure a positive customer experience, you must develop a suitable content strategy. As demonstrated in this workshop, 2015 STC Technical Communication Summit Proceedings



Don’t Just Shrink It; Rethink It!

a key to providing effective mobile and wearable content is creating prototypes. Use the exercises in this workshop to create prototypes that embody these best practices: •

Make messages positive and meaningful

•

Provide a tour to get users quickly on task

•

Minimize content for wearables

For details on this workshop, see the slides on SlideShare: http://www.slideshare.net/MartaRauch

Resources Marta’s Presentations and Publications SlideShare, http://www.slideshare.net/MartaRauch Pinterest boards on mobile and wearables http:// pinterest.com/martarauch/ Articles on mobile and wearables, Wearable Technology and Google Glass—Why It Matters Mobile Usability Guidelines, Mobile Documentation Mobile and Wearables Jakob Nielsen, Ralica Budiu, Mobile User Experience: Limitations and Strengths Katie Sherwin, Password Creation: 3 Ways to Make It Easier Don Norman, The Paradox of Wearable Technologies Joe Welinske Developing User Assistance for Mobile Apps Rachel Hinman The Mobile Frontier, Practical Guide to Tactical Mobile Prototyping Nathan Curtis Sketching for Understanding, The Power of Sketches, 6 Tips for Organizing Sketched Artifacts Lucidity Idea to App: How to Make a Mobile App Mobile Luke Wrobleski, Josh Clark, Theresa Neil OS guidelines: iOS message guidelines, Android message guidelines, Operating Systems Wearables Gartner’s Hype Cycle for Emerging Technologies, 2014 http://www.gartner.com/newsroom/ id/2819918 Mary Meeker, Internet Trends 2014 http://www. kpcb.com/internet-trends

Ultan O’Broin Wearables User Experience Heuristics for the Enterprise Prototyping Prototyping Tools http://keynotopia.com/ Stencils http://www.uistencils.com/ Usability testing with paper prototypes http://vimeo. com/48675078 Paper Prototyping Paper In-Screen Prototyping Streamlining Design with Paper Prototyping Using paper prototyping to manage risk Design Better and Faster with Rapid Prototyping Dan Roam, Back of the Napkin

Author Contact Information Marta Rauch Senior Principal Developer Oracle @martarauch Jennifer Stout Principal Technical Editor Oracle @jennylauren123

Author Biographies 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 challenges for mobile apps, gamification, beacons, augmented reality, and the next generation of mobile, wearable technology. A frequent presenter for conferences and webinars, Marta has published mobile and wearable articles for IEEE, HCII, STC Intercom, and CIDM Best Practices. She contributed 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. An STC Associate Fellow, Marta has received 15 STC awards for individual and team projects at the regional and international level. She is VP of STC 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 writing 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 maintaining policy/procedure documents.

I

mplementing or maintaining policy/procedure documents is an enormous, yet rewarding responsibility. Here are six lessons I have learned about getting started in policies and procedures.

Lesson 1: Learn the lingo Although many people use the terms “policy” and “procedure” interchangeably, they actually represent two different concepts. In his book Establishing a System of Policies and Procedures, Stephen Page defines policy as a “predetermined course of action established as a guide toward accepted business strategies and objectives” and procedure as a “method by which a policy can be accomplished…the instructions necessary to carry out a policy statement.” In other words, policy explains what must take place, and procedure states how to enforce the policy. Being able to distinguish between policies and procedures makes the documentation process easier. In her presentation Defining Policy, Procedure, and Other Governing Documents, Emily Kowal explains that having standard definitions of policy and procedures makes it easier to author and edit documents, as well as lends consistency and authority to the documentation.

Lesson 2: Use a Document Template One element that greatly helped me in maintaining our department’s policy/procedure library was establishing a standard document template. The template covered not only how information is presented, but also how changes are documented, and when. Doing so enabled me to better manage content and make it more user-friendly. •

Templates save reading time by enabling the reader to locate information more easily.

•

Templates add credibility and authority to a document. Which document looks more official: the one with a heading and consistent formatting, or the document that looks as if were merely pasted into a document file with no formatting whatsoever?

•

Templates make documents look more appealing and easier to read. This does not mean having to use the splashiest graphics or the prettiest font. Documents still need to be readable across all platforms, and convey the appropriate tone. For example, in our department, we incorporate our pharmacy logo in the upper left corner of the page, along with formatted title and most current 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 with SharePoint Although any document-sharing platform can be used to host policy/procedure documents, I can best speak about SharePoint because we use it at our company. Within our department site, I created a separate document library just for our policy/ procedure documents. This enabled me to create custom settings that would not otherwise apply to other document libraries. The following SharePoint features are especially beneficial in managing policy/ procedure documents: •

Versioning. When versioning is enabled, the system saves prior versions each time a new version of the document is uploaded. Flag the system to save all versions, not just the last few. This is especially valuable in looking up which policy applied during a given timeframe. All I have to do is bring up the version history and see which version was applicable during the given date.

•

Collaboration. To ensure that only one version is being edited at any given time, require that documents be checked out before they can be edited. Have the review committee work from the document library instead of working from emailed copies.

•

Permission Levels. Take advantage of SharePoint’s capability to designate different levels of access. Designate who should have edit access to the documents; limit access to just those individuals. For everyone else, read-only access is sufficient.

•

Major vs. minor (draft) versions. Select the option to save both major and minor (draft) versions. That way, your audience can view the most current published version, while you and your team can collaborate on future drafts.

•

Categories. SharePoint enables one to easily organize and display your documents by category and sub-category.

•

Documenting revision history. SharePoint enables you to document the revision history each time you check in a different version of the document. When you do view the version history of a policy/procedure document, you can view the revision history at-a-glance. Of course, this can be documented on the document itself as well.

150

Overall, the flexible and customizable nature of SharePoint makes it an effective tool for hosting policy/procedure documents.

Lesson 4: Spread the Word After policy/procedure documents are created and/ or modified, users need to know about them so they can begin following them. Use one or several of the following options to communicate information to users: •

Email

•

Memo

•

Conference Call / Webinar

•

Webinar

•

Job Aid

•

eLearning Module

•

Instructor-Led Training

As to which option (or options) to choose: that is your call. Just consider time and available resources you have available, and work from there. If you require others’ assistance (such as instructional design needs), take that into consideration. The main point is to make sure people know what they need to know.

Lesson 5: Don’t Let the Document Grow Stale—Review! Once written, policy/procedure documents need to be reviewed on a regular basis to make sure they still apply. Page recommends that documents be reviewed at least annually. Due to the dynamic nature of our department, many of our documents are reviewed and edited more often than that.

Lesson 6: Learn from Others This is by far the biggest lesson I have learned. When I first began managing our policy/procedure library, I never realized so many policy and procedure resources exist! I found Page’s book series on policies and procedures to be quite beneficial; he provides a wealth of resources and links to templates that I still find beneficial.

2015 STC Technical Communication Summit Proceedings



Getting Started in Policies and Procedures: Lessons Learned

Perhaps one of the best resources is by engaging with other policy and procedure professionals. •

Collaborate with peers in your department or company who also work in policies and procedures. Your human resources department may be able to help you with this.

•

Join virtual groups. Search “policies and procedures” groups on Linked. If you belong to the Society for Technical Communication, join the Policies and Procedures Special Interest Group. Within this group, you can subscribe to their discussion list and be able to ask questions and seek advice from P&P professionals worldwide.

In retrospect, I wish I had known about all these resources when I first started managing our policy/ procedure library. Having all these examples at my fingertips would have made things so much easier. In conclusion, there is no one correct way to establish policies and procedures in your department. The keys are consistency and communication. Just remember: the primary goal is to generate content that can be easily and readily referenced, so that users will remain compliant with policy.

Resources Kowal, Emily. Defining Policy, Procedure, and Other Governing Documents (Proceedings, STC Summit Conference, 2013).

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.

Author Contact Information Jamye Sagan Pharmacy Communication Advisor H-E-B 646 South Flores Street South Building, 1st Floor +1.210.938.8526

Author Biography Jamye Sagan works for H-E-B, a retail grocery chain based in San Antonio, Texas. As the Pharmacy Communication Advisor, she manages communications between the corporate office and the store pharmacies. She also maintains the policy/ procedure documents for the Pharmacy department. A Senior Member of STC, Jamye serves in various capacities, including Surveys and Membership Volunteer for the IDL SIG. She also serves as the SIG Liaison for the Community Affairs Committee, as well as a member of the Community Achievement Awards/Pacesetter Award committees. Contact Jamye at [email protected].

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

•

W

Establish appropriate life cycle(s) for reviewing and refreshing material

•

Compare estimated costs to projected return on investment (ROI)

hen we talk about technology for policies and procedures, we’re mainly talking about computer software. These programs facilitate the key functions for developing and maintaining policies and procedures:

Organizations, industries and/or markets may dictate project-specific tools:

•

Word Processing

•

Applicable laws, regulations and standards

•

Reviewing

•

•

Publishing

Lexicons or glossaries of standard terminology

•

Archiving

•

Taxonomies or classification systems

• Style guides for writers and editors Most companies use generic business software. • Professional organizations Microsoft is the 600 pound gorilla in the room. 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. 3304 Carrier Drive Other Tools Dayton, Ohio 45429 +1.937.298.3978 Use your technical communication skills to first identify the purpose, audience and requirements, and then address them effectively.

Use business tools to align with organizational goals: •



Identify key stakeholders who must be satisfied

Author Biography Louise Tincher has 20 years of experience writing and editing a variety of technical documentation. She creates order from chaos by developing and 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), including: avionics, electrical systems, financial services, government contracts, inventory tracking, hardware, logistics, maintenance, process improvement, proposals, requests for proposals, RFID, robotics, and software.

154

2015 STC Technical Communication Summit Proceedings



2015 STC Technical Communication Summit Proceedings

Technology and Tools in Policies and Procedures

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 website 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.

W

riting developer documentation offers a unique opportunity for you to expand your writing skills and enhance your technical expertise. You can build developer documentation for your organization by relying on those basic survival skills that you currently use to create rapport with your development teams, identify content needs for end-users, and write for audiences with varying technical expertise. This paper discusses key strategies for using minimal resources to create documentation that provides useful information and supports the adoption of your API by third-party developers. These strategies include identifying key content, optimizing code samples, undertaking usability testing, and performing other tasks that are crucial to the successful development of your website.

API? SDK? Before we investigate building a web site, you need to understand some basic terminology commonly used to discuss documentation written for software developers. You may already be familiar with the acronym API used as an abbreviation for application programming interface. An API includes the tools

used by third-party developers to build applications on an existing code base. These tools simplify this process by providing public pieces of code that reference functionality already implemented by an internal development team. You may also have come across the acronym SDK used to represent software development kit, which is also a set of tools used by developers to build applications with your API. In this case, the toolkit consists of the libraries that contain the code referenced by third-party developers, utilities used to facilitate implementing an application, code samples illustrating how to use your API, and other resources. In addition, you need to understand some of the basic concepts for object-oriented (OO) programming languages, since this paper focuses on documenting APIs used by languages, such C# or Java. When developers write code for OO languages, they model it on real-world or business entities. They write the backend code that controls the functionality or features exposed in the API. For example, a development team might write an API for a technical communication application that tracks the activities 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 and behaviors of a writer. The team also adds fields 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 determine the behavior of a writer or tasks that a writer can perform, such as outlining, writing, and proofreading.

adoption strategy to make a stronger case for these and other resources that you may need.

Ramp up Your Technical Skills To ramp up your technical skills, begin by identifying the programming language and other technologies used by your development team to build the API. You need this information to develop your technical vocabulary and the ability to read code samples. These skills help you formulate useful questions about the features implemented by your development team, as well as facilitate your ability to write the documentation.

A developer uses this class as a template to add multiple technical writers to the application, such as Mary, Andrei, and so on. These individual representations of technical writers are called instances of the technical writer class. A developer can then implement code that assigns the task of proofreading to one of these instances, and supplies the name of the file for this task. As an API writer, you document how to create these class instances, how to set their properties, and how to use the methods that control their behavior.

Talk to your developers about the integrated development environment (IDE) that they use to write code, and install it on your computer. Similar to the software used for developing documentation, an IDE provides developers with a specialized editor that facilitates writing code, and supports building the libraries that they provide as part of the API. Just as you would investigate the GUI for user documentation, become familiar with the IDE to understand how developers build applications in the programming language used for your API.

API Adoption Strategy An organization implements an API so that other developers can consume it by writing their code, which references or uses its functionality. In most cases, organizations want external developers to use their API to extend product features, as well as to encourage the use of their services or solutions. As Jacobsen, Brail, and Woods point out in APIs: A Strategy Guide, API adoption has gained a major role in the business goals of companies, such as Twitter, Amazon, Netflix, and others. As an API writer, you need to understand these goals, since a key element in this adoption process includes information about how to use the API for building custom applications or accessing the services that it offers. This information provides an important context for your work, which you can use to frame the presentation of the API’s technical components. Work with product management to identify the significant features of the API so that you can highlight this functionality in the documentation, and support your organization’s adoption goals. You also can use this API adoption strategy to highlight your needs for resources to support documentation development. When building out your first website for an API, you may need additional developer time for reviewing content, writing code samples, and creating sample applications. You can use this understanding of your organization’s API 158

While developing your technical skills may initially seem daunting, you have multiple options available for learning about the technology used by your organization. Microsoft provides free videos and training materials in C#, while Oracle offers tutorials and training in Java. You may find the study guides for language certifications particularly useful because they tend to provide succinct overviews of key language features. Watch the videos and use the tutorials to set up your own development environment. Build the sample applications described in the tutorials so you can learn about features of the language and have fun running your own applications. Depending on your current technical expertise, you may want to plan for about twenty hours of ramp up time to master terminology and to understand basic code samples.

Content for Your First API Website One of the many advantages to ramping up your technical skills is that you start to understand the types of information, which developers may want in order to work with your API. Your website content should meet the needs of developers with a range 2015 STC Technical Communication Summit Proceedings



Survival Strategies: Building Your First Website for API Documentation

of technical expertise. This audience may include entry-level developers just out of college; developers with no prior background in the technology used by your API; or experienced developers who just want information about a specific API feature.

ignore explanatory content, no matter how well written, in favor of your code samples. While complete and accurate explanatory content is a significant component of your site, you also want to include well-written code samples for all key API operations.

While websites differ based on the functionality provided by the API, they generally include content that falls into these categories, which take into consideration varying levels of technical expertise:

Work with your development team to establish a clear strategy for writing code samples, even though this task may not be a priority for the team. Look for opportunities to optimize the development of this content by reusing code from sample applications or QA test cases. In addition, consider the different types of code samples that you need to illustrate operations in all the programming languages supported by your API:

•

•

•

•

Concept information - provides a high-level overview of the features and architecture of your API, as well as an explanation of the relationships between different classes represented in the object model. It may also discuss best practices for implementing features and improving performance. Tutorials or getting started materials - provide instructions for installing the SDK and setting up a development environment. It may also include simple tutorials that provide systematic instructions for implementing a simple application or consuming some feature provided by your API. This content offers the opportunity to illustrate best practices for using your API, and to highlight its user-friendly features. Code samples - includes short fragments of code and longer more detailed code samples, as well as complex code samples or even entire sample applications. Class libraries - provide reference material generated from comments entered in the source code during the development of the API. As an API writer, you may author this content, which provides descriptions of classes along with their properties and methods. For example, you would use the class libraries to find the methods supported by the technical writer class, such as outlining or writing.

If you are familiar with DITA or content modeling, you may want to tag the different content types, and then use these techniques to structure the information on your site.

Code Samples Show me, don’t tell me. This phrase sums up the significance of code samples for developers learning how to use your API. They may skim or outright

•

Short snippets - use these code samples to illustrate a single feature discussed in your conceptual or overview content. This code may consist of two or three lines.

•

Codes samples for methods or classes - use these codes samples to provide a detailed example of a specific API feature. They also might be part of a step-by-step tutorial, and may consist of ten or more lines.

•

Sample applications - use these code samples to illustrate complex projects and application design with your API. These samples may include multiple files.

In addition, make sure that you format your code samples using syntax highlighting to enhance readability. Syntax highlighting color-codes specific words and other elements in your code samples. Different colors indicate code comments that aren’t functional parts of the code, variables and other elements defined by a developer, and reserved words that are elements of the programming language.

Tools for Building Your Site You may face multiple constraints when choosing tools to build your site. The conceptual content, tutorials, and other explanatory material may be written in the tool that you are currently using to develop user documentation, such as Madcap Flare, Robohelp, or other systems. However, you generate the class libraries, which provide your most significant 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 generate class libraries for C#, while Javadoc tends

2015 STC Technical Communication Summit Proceedings

159

API Documentation

to be the tool of choice for the Java programming language. The repository that your organization uses to store the source code for your API may also have a significant impact on how you provide comments for the class libraries. Some organizations limit the access of the technical writer to the source code, so that adding comments becomes a complicated process. The repository used to house the source code can facilitate this process by providing a review workflow that allows writers and developers to collaborate when adding or editing comments. If you have the opportunity to choose the tools for your first website, consider these features during the evaluation process: •

Authoring and collaboration capabilities

•

Learning curve for current and new documentation team members

•

General web publishing functionality and support for community portals

•

Options for integrating with source control products

•

Flexible formatting and other customization options

•

Costs for proprietary versus open source tools

•

Compatibility with other tools used by your organization

Investigate Your User’s Experience Usability testing provides important insights about how developers navigate your website and their expectations for it. In Rocket Surgery Made Easy, Steve Krug outlines a no frills approach to usability testing that you can use to modify your site to improve the user experience. We learned that most of our developers search rather than browse our documentation site. Furthermore, they prefer to search our content with Google, rather than use the searching functionality available through the site itself. We have used this information to identity site designs that to facilitate this approach to searching.

with these users, then consider asking co-workers to participate in the process. You can structure your usability tests to take only about an hour, which is a minimal investment of time. Consider recruiting new hires for your development teams. Entry-level developers can provide insights about content designed for users developing their technical expertise. In contrast, more experienced new hires can provide insights about content developed for the advanced users. If you are building the first API documentation website for your organization, recruit developers working on projects other than the API. They provide yet another perspective about the documentation, since they are familiar with your products but not necessarily the API. Look for trends and commonalities in comments made across these groups, and make updates as necessary.

What Is SEO? Why Do I Need It? For developer communities, content must be accessible through Google or it might as well not exist. Developers tend to prefer searching for information rather than browsing through a complex navigation structure no matter how well organized. They expect to find information about public APIs by using one of the major search engines. For this reason, you want to develop your familiarity with the concept of search engine optimization (SEO). SEO includes the process of ensuring that your content is discoverable by major search engines. While technical details of search algorithms are proprietary, you can find general information about how they index the content of your site, which helps you understand how external search engines see your documentation. You can ensure that queries return meaningful results by taking basic steps to optimize this process. When building your website, you also want to pay close attention to design details that may influence the ability of developers to search your content. Some page designs may make your web pages difficult to index, such those that use IFRAME elements. In addition, you may want to consider adding metadata 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 When building your first API documentation website, you may perform certain repetitive tasks manually, such as building the class libraries or publishing your site. These types of tasks offer the opportunity to utilize automation in your API documentation project. The generation of class libraries, the API reference information, lends itself to automation due to its highly structured content. The tools used to generate this content include Sandcastle, Javadoc, Doxygen, and others, which provide output that can be produced by an automated build process. The inclusion of code samples in your website offers another opportunity for automation. You might initially find yourself copying and pasting code samples into your documentation project. Consider working with your development team to explore an automated solution, which would eliminate your manual steps and ensure that code samples in the website stay up-to-date.

session offered by Ed Marshall, Intercom’s API issue edited by Tom Johnson, and webinars hosted by Sarah Maddox. You can tailor all of the strategies discussed in this paper to your organizational goals, resources, and the needs of your external developers. They highlight fundamental challenges implicit in the development of a website for API documentation, while also offering opportunities to create a rich user experience for your developer community. Devise a successful survival strategy! Don’t get voted off the island!

Resources Jacobsen, Daniel, Greg Brail, and Dan Woods. APIs: A Strategy Guide (Sebastopol, CA: O’Reilly Media, Inc.), 2012. Krug, Steve. Rocket Surgery Made Easy, New Riders, 2009. Linderman, Mary. “Lessons Learned as a Novice API Writer.” Intercom (September 2014): 16-18. 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 you have the technical expertise or resources for these enhancements. Establish consistent naming conventions for files and other content elements to facilitate building integration points in your documentation project as you have more resources and opportunities to automate your processes.

De Kort, Wouter, Exam Ref 70-483: Programming in C# (Sebastopol, CA: O’Reilly Media, Inc.), 2013.

Strategize for the Future

Sierra, Kathy and Bert Bates. Head First Java, 2nd 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 opportunities to balance your current goals for the site with its future growth and evolution, so that you can be responsive to the development of new APIs. For example, will your current toolset support the growth of your APIs? If not, can you structure your current content to simplify its migration to another system? New trends in technical communications can also help you strategize for future iterations of your site. Other sites hosting API documentation often provide useful insights about how you might want to continue evolving your site. In addition, technical communicators continue to develop useful resources about writing API documentation, such as training

References

Greene, Jennifer, and Andrew Stellman. Head First C#, 3rd Edition (Sebastopol, CA: O’Reilly Media, Inc.), 2013.

Author Contact Information Mary Linderman Senior API Writer kCura LLC 231 South LaSalle Street, 8th Floor Chicago, IL 60604 +1.872.800.6432 Andrei Essaoulov Senior API Writer kCura LLC 231 South LaSalle Street, 8th Floor Chicago, IL 60604 +1.312.870.5511

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 thirdparty 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? Brenda Huettner, Fellow

167

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 advice of a legal processional. Please consult one in your area.]

P

roposals do more than set your price. They establish the guidelines for the project, covering everything from deadlines to payment terms. Because they are negotiated in moments of calm—not during the chaos of an emergency or deadline—a well-defined proposal ensures that both sides enter into the relationship with rational expectations.

Legwork: Do Your Research The more knowledge that you have going into a project, the more you are able to keep things from going off the rails. Even a 15-minute discovery call can uncover details that don’t appear in a written project plan. Listen for the nuance as the prospective client 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 to get this done? By listening to the pauses, the clarifications and the asides, you’ll quickly identify red flags, internal politics, and expectations.



More Detail is Better In most companies, projects of a decent dollar amount require the signature of an executive, someone in Finance, or both. Deliver a detailed proposal that not only addresses the topics covered by the client contact, but also highlights every conceivable element that might be necessary to push that proposal through the hierarchy and get the signatures needed.

Negotiate! Some will say that large companies won’t negotiate. Not so! Even multinational, multi-billion-dollar corporations will negotiate pricing, payment terms, deadlines and responsibilities. Stick to your guns and be prepared to walk away if something doesn’t work for you.

Create a Template When you use a proposal template, you are less likely 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, editing

•

The goals of the project: are we on the same page?

•

Limitations and recommendations

•

Review and approval

•

If flat rate: how many rounds of revision are included

•

When invoices will be submitted

•

Payment terms

•

Scope changes and rush fees

•

Signature page

•

Addendum: who are you, and why are you worth it?

in the areas of medical devices, pharmaceuticals/ genomics, network security and healthcare IT. She has been a member of the American Medical Writers Association (AMWA), the Society for Technical Communication (STC), the Public Relations Society of America (PRSA) Health Academy, and the San Francisco Chapter of the International Association of Business Communicators (IABC). She has spoken about professional development to audiences at the Creative Freelancer Conference, the American Society of Journalists and Authors (ASJA), IABC, STC and AMWA.

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, interests, and work styles to help you identify which format is best for your specific situation.

D

eciding where and how you want to live and work isn’t easy. Some people prefer to work alone; others prefer to work in groups. Some people like to maintain a lot of control over what they do; others like to have a lot of guidance.

And, sometimes, you need to take into consideration things other than the workplace itself – there are lifestyle and family issues that often require choices you might not have otherwise made.

Know Your Options The workplace is more varied now than ever, with a wide range of employment types and corporate job offerings. Before you make any decision, you need to understand what some of the options are.

and sometimes limited benefits such as holiday pay or retirement benefits if you work more than so many hours in a year. But this type of job usually has a pre-defined end date – it’s just for the summer or the holiday season or while someone else is out on sick leave. The company still deducts taxes from the employee salary. A part-time employee works directly for a company, 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 company still deducts taxes from the employee salary. An agency employee sometimes looks like a temporary employee or a contractor, but is actually

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 company and gets salary (usually hourly), withheld taxes,

Figure 1. There are many different ways to describe the status of a worker. 167

Consulting and Small Business Management

an employee of a different company (the agency) and as such, would get the holiday, retirement, and other benefits of being an employee. The agency is responsible for deducting taxes. It’s usually hourly work, with a variety of clients, and can be very steady if you are good at what you do and have a good relationship within the agency.

•

Employer provides insurance options

•

Employer helps with retirement funds

Contract

A consultant generally advises about a specific job or topic, often recommending tasks that someone else will actually carry out. The pay is usually flatrate – that is, a single amount for a specific job. Consultants often get higher pay for more experience, and it’s unlikely anyone would start out this way.

But for the purposes of this paper, we’ll consider Contract to be any of the jobs that aren’t direct employees for a single company.

Paid vacation, holidays, sick time

Compare and Contrast: Taxes and Admin

A contract employee (or contractor) works directly for a company for a set period of time for a set salary but no benefits. In theory, this allows the salary to be higher (though it doesn’t always work that way). The employment agreement is set out in a contract that can be long or short term, but always has an end date, that can be hourly or weekly or by milestone. The contractor is responsible for paying taxes and often for other expenses.

A freelancer does a specific task, think “magazine article” or “white paper”, for a specific amount of money (not tied to the amount of time it takes).

•

•

Must always be looking for next client or opportunity

•

Responsible for paying estimated taxes (1099)

•

Responsible for 100% of Social Security

•

Must submit invoices, sometimes several times

•

Captive

•

You usually know what you’ll be doing next year

•

Employer withholds taxes (W-2)

•

Employer pays 50% of Social Security tax

•

Some companies require time cards, status reports

Compare and Contrast: Legalities Contract •

It isn’t called “contract” for nothing! You need one for EVERY job

•

You can negotiate which rights belong to you and to the client

•

Be careful of your status! Tax laws vary, and the IRS keeps a close eye on contractors

Compare and Contrast: Money and Benefits Contract •

Higher Hourly Rate

•

Must pay expenses (but they’re deductible)

•

Pay for own professional development (training, conferences, etc.)

•

No pay for time off

•

Must arrange and pay for insurance

•

Don’t forget retirement!

Captive •

Steadier rate of pay

•

Employer pays expenses

•

Employer (often) pays for professional development

168

Not generally covered by labor laws Captive •

Employee Handbook (if any) spells out what you need to know

•

Employer usually owns all rights to everything you do

•

As an employee, you have certain rights (IRS vs. Microsoft)

•

Laws exist for things like overtime, breaks, protection from unfair termination

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 started?

Contract •

Take as much vacation as you want, when YOU want it

•

Are you disciplined about saving for a rainy day or during down time?

•

Vacation, sick time, and holidays are unpaid

•

•

Unpaid time between assignments

Do you have a home office and all the equipment you’ll need? Home office can be a range of things – from kitchen table to separate building. Some jobs want you in their office, others don’t.

•

Do you have or are you willing to buy the required software packages? For contractors, as for companies, this is an ongoing business expense, keeping up with latest releases and new types of software.

•

Can you accurately estimate how long it takes you to perform specific tasks? Estimating is a learned skill—the more you do the better you get at it. You might lose jobs (if bid too high or too many hours) or lose money (if too low) until you get it right.

Captive •

Predefined number of vacation days, and sometimes sick days

•

Employer pays for vacation, holidays, sick days

•

No unpaid “down time”

Know Yourself Once you’ve got a good handle on the types of work available, you need to ask yourself some pointed questions before determining whether you’re better suited as a contractor or an employee.

•

Are you covered under an insurance plan? You’ll need all kinds of insurance – health, dental, life, but also (sometimes) errors & omissions or other liability plans. As a contractor, there’s usually no worker’s comp, no unemployment insurance.

•

Are you good at paperwork? You’ll need to do your own book keeping, invoicing, taxes, state filings, and more.

•

Are you good at networking? This is more than just going out to an occasional meeting, it also includes things like telling people how good you are at your job.

•

Do you have a wide range of experience and tools knowledge? Companies are more likely to hire contractors who already have the skills they’re seeking.

•

Do you like working by yourself? This may seem contradictory to getting along well with others, but you need both skilss to be a successful contractor. You don’t usually have a team of people to help you.

Are you flexible about when you work? This could be late nights or early mornings (think India time zone at 12.5 hours difference) or could be weekends.

•

Are you good at planning your time? You’ll need to schedule your own time, learn to prioritize, particularly if you have multiple projects .

Are you flexible about how much you work? There might be no work at all for weeks and then a month or two of 80-hour weeks.

•

Are you flexible about the kind of work you do? If you’re an editor, you might need to sometimes write (and vice versa).

Pop Quiz! Count your “YES” answers: •

•

•

•

Are you self-disciplined? If you have a deadline, do you do a little everyday or put off until almost due? Would you sit down to work if no one is watching you? Can you get the job done if it is a nice sunny day or the kids want to swim or the dishes need washing? Is it hard to distract you from the task at hand? Do you get along with different types of people? Even if you’re working by yourself, you still need to convince the client you are the man or woman for the job, get info out of SMEs (same as employee, deal with accounting/bill payers, and often a “permanent” staff who may be thrilled you are helping but may also resent you.

2015 STC Technical Communication Summit Proceedings

169

Consulting and Small Business Management

•

Can you handle many tasks at once? While this one certainly includes things like working on multiple projects or documents or clients (as employees sometimes have to do), it also means that sometimes you need to be writing but also marketing your business or invoicing.

•

Do you have a strong personal support system? Support system – family, esp. when working at home, need to give you space/time/quiet or whatever you need.

•

Are you good at what you do? A contractor’s success is dependent on repeat business and referrals.

•

Do you enjoy what you do? None of this will work without passion.

Author Biography Brenda Huettner is an independent technical communication consultant specializing in increasing her client’s awareness of the benefits of quality documentation. An active member of the professional community in the Tucson area, Brenda has worked as a technical writer, technical editor, trainer, usability consultant, documentation department manager, Help author, content developer, graphic artist, and webmaster. She’s written a wide variety of content for audiences of end-users, programmers, and engineers. In addition to contract work through her own consulting company, P-N Designs, Inc., she maintains three Web sites and has several commercially published books in print. 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 published several books and articles, and presented halfday, full-day, and multi-day courses on writing, project 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 different 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