Communicate the Future PROCEEDINGS HYATT REGENCY ORLANDO 20–23 MAY | ORLANDO, FL and Summit.Stc.Org #STC18

Communicate the Future PROCEEDINGS HYATT REGENCY ORLANDO 20–23 MAY | ORLANDO, FL www.stc.org and summit.stc.org #STC18

SOCIETY FOR TECHNICAL COMMUNICATION 1 Efficiency exemplified Organizations globally use Adobe FrameMaker (2017 release) Request demo to transform the way they create and deliver content

Accelerated turnaround time for 70% reduction in printing and paper customized publications material cost

Faster creation and delivery of content 50% faster production of PDF for new products across devices documentation

20% faster development of Accelerated publishing across formats course content

Increased efficiency and reduced 20% improvement in process translation costs while producing multilingual manuals efficiency

For a personalized demo or questions, write to us at [email protected]

© 2018 Adobe Systems Incorporated. All rights reserved. The papers published in these proceedings were reproduced from originals furnished by the authors. The authors, not the Society for Technical Communication (STC), are solely responsible for the opinions expressed, the integrity of the information presented, and the attribution of sources. The papers presented in this publication are the works of their respective authors. Minor copyediting changes were made to ensure consistency. 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. © 2018 Society for Technical Communication 9401 Lee Highway, Suite 300 Fairfax, VA 22031 USA +1.703.522.4114 www.stc.org

Design and layout by Avon J. Murphy and Allison Gisinger

2018 Society for Technical Communication Summit ...... vi Overview ...... vi Conference Committee ...... vi

Accessibility: Future-Proofing Your Web Content ...... 1 Shadi Abou-Zahra

Fueling Your Future: STC Experience Builds Professional Leadership Skills ...... 7 Bethany Aguad, Crystal Brezina, Nick Ducharme, and Alex Garcia

Give in to the Power of the Dark Side: Marketing and TC are Converging! ...... 13 Bernard Aschwanden

Plan for Tomorrow: Project Management and Technical Communications Fundamentals ...... 16 Bernard Aschwanden

Teaching Technical Writing to Engineers—What Works? ...... 19 Noel Atzmiller

LIGHTS, CAMERA, ACTION: Exploring Video Basics for Non- Production Professionals ...... 23 Darcy Beery and Stacy Barton

Won't You Please, Please Help Me Find a Path to Leadership? . 29 Alisa Bonsignore

Case Study: Grab the Wheel and Drive Your Content to DITA ... 31 Susanna Carlisi, Tom Aldous, and Adobe

iii Table of Contents

Your Mind is the Most Valuable CMS: Deeper Working Independent of Technology ...... 37 Kim Chmielewicz

Policies and Procedures—Communicate the Future...... 39 Dawnell Claessen, Emily Kowal, and Ann Marie Queeney

Moving Content through the Workflow: Frustrations and Fixes 41 Erica Cummings

Using Regular Expressions with Madcap Flare: Putting Your Searches on Steroids ...... 45 Robert Delwood

Dethrone the Content King! Culture is the True King...... 52 Jamie Gillenwater

Can You Hear Me Now? Podcasting as a Teaching Tool ...... 56 Jennifer Goode

Scoped Out! ...... 59 Sarah Kiniry

Science-Based Page Design for Technical Communicators ...... 68 Tina M. Kister

UI/UX Design Crash Course ...... 83 Jessica Kreger

They’re Coming! Combining Teams and Cultures ...... 85 Larry Kunz

All I Know About Collaboration I Learned from Rock & Roll ...... 89 Aiessa Moyna

iv 2018 STC Technical Communication Summit Proceedings Table of Contents

From Open Source Volunteer to Full-Time Tech Writer ...... 92 Gale Naylor

Creating and Training Your Own AI Instance Using DITA ...... 96 Vishal George Palliyathu

PICTURE PERFECT! How to Turn Words and Data into Powerful Graphics ...... 102 Mike Parkinson

Lessons Learned: What Harry Potter Professors Teach Us About Instructional Design ...... 106 Jamye Sagan

From Technical Writer to Content Strategist ...... 113 Melanie Seibert

A Method for the Madness: Managing Complex Documentation Projects...... 118 Jennifer Shumate

An Information Experience (IX) Maturity Model for Organizational Transformation ...... 125 Sudhir Subudhi

Artificial Intelligence and Content...... 129 Val Swisher

How Tech Writers Will Support SMEs in Writing Technical Content ...... 131 Søren Weimann

The Introvert in the Workplace: Becoming an Influencer and Leader ...... 134 Ben Woelk

2018 Society for Technical Communication Summit

Overview The 2018 Technical Communication Summit takes place from 20-23 May at the Hyatt Regency Orlando in Orlando, Florida. This 65th annual Summit offers more than 60 education sessions over three full workdays with topics covering all aspects of technical writing, editing, graphic design, information design, usability, project management, and publication production. Practitioners, professors, researchers, and students at all levels of experience convene to learn from expert presenters and from each other.

Conference Committee The Conference Committee builds the conference program by managing the call for proposals, reviewing the proposals, and selecting speakers who can present information on a wide variety of topics of interest to attendees.

Phylise Banner David Caruso Track Manager Conference Chair Learning & Design

Louellen Coker Deborah Krat Track Manager STC Education Manager Career Development

Toni Mantych Liz Pohland Track Manager STC Chief Executive Officer Technology & Development

Bobbi Werner Marilyn Woelk Track Manager Program Manager Writing & Communication

Accessibility: Future-Proofing Your Web Content Shadi Abou-Zahra, W3C Web Accessibility Initiative (WAI)

The Web has come a long way from its static and document-oriented origins to today’s highly rich and dynamic web-based applications. Yet there is much more to come. Advances in natural language processing allows for increased voice-based and multi-lingual interactions, and artificial intelligence applications allow for on-the-fly adaptations and personalization of web content. At the same time, web-based virtual-, augmented-, and mixed-reality applications are emerging and rapidly evolving. These technological advances provide unparalleled opportunities for people with disabilities. At the same time, ensuring accessibility of your web content today facilitates its uptake by the emerging technologies of the future.

Background—What is Web Colors with Good Contrast Accessibility Some people have Web accessibility means that people with disabilities different color percep- can use the Web equally. That is, people can navi- tions, and cannot dis- gate, access, and interact with the web content tinguish certain com- without barriers due to auditory, cognitive and neu- binations of fore- rological, physical, speech, or visual disabilities. For ground and back- example, this includes captions for audio content, ground colors. It is particularly the case for a large functionality that is easy to use and information that number of adult men. Ensuring good contrast allows is easy to understand, functionality that can be op- more people to accurately perceive the content. erated through keyboard, voice, and other input mo- This includes people with some types of visual disa- dalities, and text alternatives for images and other bilities. It also benefits people in bad lighting condi- visual content. The following examples of are from tions, such as glare when they are using a mobile the video series “Web Accessibility Perspectives” device in the sun. (W3C, 2016). Clear Layout and Design Keyboard Compatibility Most people are over- Some people cannot whelmed and con- use the mouse. This fused by overly com- includes people with plex layout and de- physical disabilities signs. For some peo- and people who are ple with cognitive and blind. Functionality learning disabilities, this can be exclusionary. Also needs to be operable by keyboard in addition to the people with visual disabilities often rely on a good mouse, touch, and other input modalities that devel- layout and design to orient themselves and navigate opers choose to support. This supports voice the content. Clear layout and design is especially browsing, which commonly uses the keyboard inter- important for people who are new to computers, face as well. It also supports people with situational which often includes older people and people with limitations, such as broken mouse or broken arm. lower literacy skills.

1 Shadi Abou-Zahra

Text to Speech Customizable Text Some people cannot Some people have see, and rely on an difficulties processing audio form of the context in particular font tent. They often use types, colors, and specialized screen spacing. There is no reading software, one form to address which reads aloud the content. Several computer the variety of individual needs and preferences. operating systems today have text to speech func- Some browsers provide functionality to customize tionality built directly into them because it is useful how text is presented for oneself. Content needs to to many more people in different situations. This in- be coded in such a way that it can be presented dif- cludes reading aloud websites, emails, and e-books ferently. Yet this does not replace the need for de- while multi-tasking. Content needs to be correctly signers to consider the accessibility of the default coded for this to work. presentation of the content.

Large Links, Buttons, and Controls Voice Recognition Some people have Some people cannot limited dexterity and use their arms. They find it hard to click on often use specialized smaller links, buttons, software to operate and other form con- the computer by trols. This is particu- voice. This includes larly relevant on devices with small screens, such dictating text but also selecting links, buttons, and as mobile phones and tablet computers. Such dex- other controls, as well as emulating keyboard input. terity limitations increase with age. Designers can Voice is increasingly used by many people, such as accommodate that by allowing more click space on for hands-free computing and to avoid repetitive and around the controls. This makes the content stress injury (RSI). Content needs to be coded so more comfortable to use by many people, including that it can be used with such voice recognition soft- people with larger hands. ware.

Video Captions Understandable Content Some people are Most people have en- hard of hearing or countered content completely deaf, and that was too difficult rely on visual form of to understand. For the content. Captions some people with are essential for ac- cognitive and learning cess to such auditory content. They are also essen- disabilities content can quickly become too difficult tial for people with some forms of cognitive and to understand and use. This includes using overly learning disabilities, such as dyslexic people who complex terminology and jargon. Also long sen- rely on seeing and hearing the content to better un- tences with complex structures, and large blocks of derstand it. Captions benefit many more people, text without headings can be exclusionary. Content such as people in loud or quite environments, and that is accessible for people with disabilities tends to non-native speakers. be more usable too.

2 2018 STC Technical Communication Summit Proceedings Accessibility: Future-Proofing Your Web Content

Notifications and Feedback learning disabilities often relate to the clarity and understandability of content and func- Not only content can tionality, which benefits all users. People be too difficult to un- who have lower computer skills, such as derstand but also many older people and others new to com- functionality. In partic- puters are especially supported by accessi- ular interaction with ble design. forms and applications can be quickly confusing for many people. • Mobile and other devices: Accessible con- Particularly people with cognitive and learning disa- tent also works better across different de- bilities are impacted by this. Also blind people who vices and technologies. For example, web- are not seeing what is visually presented may get sites that are designed to be accessible disoriented by unclear notifications and feedback tend to work better on mobile phones and from interactions. People with lower computer skills tablet computers, because they can better are commonly impacted too. adapt to the often smaller screen sizes. Ac- cessible content also supports more mecha- nisms of interaction, such as browsing by The Business Case for Web voice. This includes operating the computer Accessibility by voice, as well as hearing the content rather than seeing it. For hands-free compu- There are many benefits of ensuring web accessibil- ting, such as while driving a car, such inter- ity. The following examples are from the guidance action is essential. It also allows content to on “Developing a Web Accessibility Business Case be used on devices with different capabili- for Your Organization” (W3C, 2012): ties, such a television set-top box with only an onscreen keyboard, or an information ki- • People with disabilities: According to the osk without a mouse. World Health Organization (WHO), about 15-20% of the population has some form of • Emerging technologies: Accessible con- disability. This is a significant market share tent tends to be more compatible with older missed when content is designed to be inac- technology as well as with emerging ones. cessible. In particular, it is reported that peo- Hands-free computing in increasingly “smart ple with disabilities are often willing to pay cars” is such an example. Also “smart more and to be more loyal to services that agents” such as Alexa, Cortana, and Google are accessible. Assistant are example of how accessible design allows content to be more usable in • Ageing population: People are more likely more situations. In fact, many accessibility to acquire disability and other limitations features are increasingly mainstreamed, with growing age. As the longevity and aver- such as voice-recognition and text-to- age age continues to rise in many countries, speech. there is a rapidly growing population sharing the same functional requirements as people • Social responsibility: Access to infor- with disabilities. In addition, many older peo- mation, including digital content, is a human ple have lower digital skills due to late intro- right. This is recognized by the UN Conven- duction to computers, and are further sup- tion on the Rights of Persons with Disabili- ported by the impact of accessible design ties, which has been ratified by nearly 180 on overall usability. Older people are some- countries around the world. In a world of in- times affluent and demonstrate similar be- creasing diversity and globalization, acces- havior of customer loyalty as people with sibility and inclusion is simply the right thing disabilities. to do for any reputable organization. • Overall usability: While accessibility fo- • Legal requirements: Many countries cuses specifically on ensuring equivalent around the world have also adopted laws access for people with disabilities, most ac- and policies on accessibility and non-dis- cessibility improvements tend to also im- crimination. These commonly apply to digital prove overall usability and customer experi- content and services. They tend to refer the ence. In particular, accessibility require- W3C standards for web accessibility or ments relating to people with cognitive and some derivative thereof. The W3C Web

2018 STC Technical Communication Summit Proceedings 3 Shadi Abou-Zahra

Content Accessibility Guidelines (WCAG) is maintenance of accessible content, in line generally recognized as the global standard with the requirements defined by WCAG. for web accessibility by many governments • User Agent Accessibility Guidelines and organizations around the world. (UAAG): defines accessibility requirements for web browsers, media players, and other Resources on Web Accessibility for software used to render and interact with the content on behalf of the user. In some You cases this can include specific types of as- The W3C Web Accessibility Initiative (WAI) provides sistive technologies and mobile apps. Such a comprehensive set of freely available standards software needs to provide accessibility fea- and resources for the wide variety of relevant audi- tures and to be compatible with assistive ences. This includes designers, developers, content technologies used by people with disabili- authors, project managers and executives, testers, ties. For example, they need to play back educators, and advocates. The following example captions when these are available, and resources are from the website of the W3C Web Ac- communicate components such has head- cessibility Initiative (WAI). ings. Accessibility Standards W3C also provides the Accessible Rich Internet Applications (WAI-ARIA) web standard, which pro- The following W3C standards on web accessibility vides semantics to make applications accessible. are internationally recognized by many govern- For example, to enrich custom-made buttons in ments and organizations. They are developed in an HTML with the necessary information about their international collaborative efforts with the involve- value and behavior so that assistive technology can ment of disability organizations and end-users, ac- interact with them as they would with native buttons. cessibility experts, government bodies, researchers, WAI-ARIA allows developers to meet WCAG re- and many more. They support end-to-end accessi- quirements for applications. bility, from content production to consumption by the end-user. They include: Technical Resources • Web Content Accessibility Guidelines (WCAG): defines accessibility requirements W3C provides resources to support designers and for content, including text, forms, images developers in meeting the accessibility require- and graphics, videos and sounds, scripts ments define by the standards. The following re- and applications, and anything else pre- sources are particularly relevant for implementing sented to the end-user. The currently opera- WCAG: tional version is WCAG 2.0, with WCAG 2.1 • Understanding WCAG 2: provides more being shortly before completion. WCAG 2 background, examples, and references to has been written to be testable and agnostic help readers to understand the require- to the specific content formats being used. ments defined by the WCAG 2. This helps In turn it is sometimes applied to non-web designers and developer to understand the content, such as electronic documents, mo- intent and purpose of the requirements, thus bile applications, and other software. WCAG make them more comprehensible. 2.0 is formally adopted and referenced by • Techniques for WCAG 2: provides docu- many laws and policies around the world. mented ways of meeting the requirements • Authoring Tool Accessibility Guidelines defined by WCAG 2. This includes advice (ATAG): defines accessibility requirements on good practice beyond the bare minimum for tools and systems used to create and requirements. It also includes documented publish content. This includes content, common failures, which are known to create learning, and document management sys- accessibility barriers. tems (CMS, LMS, DMS), code editors, and • How to Meet WCAG 2: provides a customi- integrated development environments (IDE). zable quick reference guide to WCAG 2 and Also social media can be regarded as a type all the supporting materials. Customization of authoring tool because it is used to gen- includes filtering by level of accessibility, erate content. Authoring tools supporting ac- technologies used, content being cessibility facilitate the production and

4 2018 STC Technical Communication Summit Proceedings Accessibility: Future-Proofing Your Web Content

developed, and role of the implementer, • Evaluation Tools: sortable list of cur- such as designer or developer. rently ~110 tools, with guidance on selecting tools. Educational Resources • Evaluating with Users: provides guidance on involving end-users in evalua- Inaccessible design and implementation often re- tion testing. sults from lack of awareness, knowledge, and skills • Promoting Accessibility with the topic. In addition to the technical resources, W3C/WAI also provides educational resources to • Contacting Websites: provides guid- support the different audiences relevant to imple- ance on alerting website owners on bar- menting and applying the accessibility standards. riers found. These include: • Developing Training: provides guidance on building presentations and • New to Accessibility training courses. • Introduction to Accessibility: provides overall introduction to the topic and resources. Accessibility and Emerging Tech- • Web Accessibility Perspectives: short nologies videos (~1 minute) explaining different features. Standards and resources exist to make digital content accessibility. There are also many business • Components of Web Accessibility: benefits and resources to implement accessibility. explains key concepts and terminology Yet particularly with the currently rapidly evolving of the field. technologies it is more important than ever to in- • Getting Started: grain accessibility throughout the design and devel- • Tips for Getting Started: basic and opment lifecycles of content, to maximize its longev- most essential things to get started with ity over emerging technologies. The following exam- right away. ples underline this argument. • Web Accessibility Tutorials: more in- depth explanation of how to meet re- Mobile Computing quirements. Accessing content through the mobile devices, in- Easy Checks: preliminary check of con- • cluding smart phones, tablet computers, digital tele- tent, which can be carried out without visions, gaming consoles, and several more, has expertise. surpassed access through desktop in many con- • Managing Accessibility: texts. The rather sudden uptake of mobile compu- • Developing a Business Case: pro- ting was for many unexpected, and showed how ac- vides arguments and tips on building cessible content generally performed better out of business cases. the box. In fact, the W3C Mobile Web Best Prac- • Developing Organizational Policies: tices overlap with WCAG 2 in up to 90% of the re- provides guidance and tips on building quirements. As mobile computing continues to policies. evolve, accessibility becomes more relevant. • Planning and Managing: provides guidance on integrating accessibility in Internet of Things (IoT) project work. Further to mobile computing, content is becoming • Involving Users: provides guidance on increasingly ubiquitous through Internet of Things involving end-users throughout the pro- (IoT). This includes smart appliances, wearables, cess. smart environments and public spaces, and many • Evaluating Accessibility more ‘things’ that are increasingly internet-enabled. • Conformance Evaluation: a methodol- Interacting with these is increasingly through voice, ogy and report tool for evaluating entire gestures, and other non-traditional access modali- websites. ties of keyboard and mouse. Such device-independent and multi-modal interaction are key corner

2018 STC Technical Communication Summit Proceedings 5 Shadi Abou-Zahra

stones of digital accessibility, making accessible Yet often it is lack of awareness, knowledge, and content more apt for IoT. skills that leads to inaccessible designs and implementations of content. The W3C Web Accessibility Automotive Computing Initiative (WAI) provides a wealth of freely available materials to support people responsible for imple- Maybe a specific aspect of IoT is automotive com- menting accessibility. This is everybody involved puting. This is less related to the aspect of self-driv- throughout the design, development, and mainte- ing cars but rather to the increasing computer tech- nance process of content. It is essential to take up nology and internet connectivity in cars. This in- these resources and implement accessibility. cludes navigation systems and driver assistants. Implementing accessibility is not only critical today, These need to be non-distracting, easy to under- but also to future-proof your content for tomorrow. stand, and easy to use without vision and hands. Digital technology is rapidly evolving, faster than we That is, drivers have limited cognition, vision, and can often adapt the content accordingly. Accessible physical abilities while driving, yet need to interact content is specifically designed to be device-inde- with increasingly complex systems and applications, pendent, to support multi-modal interaction, and to including processing content. be easier to understand by a wider variety of audience. These concepts are prerequisites for technol- Artificial Intelligence (AI) ogies on the horizon. While the term Artificial Intelligence tends to be overused in many contexts, there is no doubt about the recent achievements in this field and the possi- References bilities it facilitates. Actually, the vision of intelligent agents that can process content and extract rele- W3C. “Developing a Web Accessibility Business vant information existed from the onset of the inven- Case for Your Organization.” Web Accessibility tion of the Web. A facilitating factor for better intelli- Initiative (7 September 2012). gent agents, such as chatbots, is content that is https://www.w3.org/WAI/bcase/. easier to understand. Such content can be more W3C. “Web Accessibility Perspectives.” Web easily processed by humans as well as by artificial Accessibility Initiative (15 September 2016). intelligence applications. https://www.w3.org/WAI/perspectives/.

Virtual-, Augmented-, and Mixed-Reality Author Contact Information (VR, AR, XR) Shadi Abou-Zahra There have been many attempts and advancements Accessibility Strategy and Technology Specialist in this field since the inception of computing. Partic- W3C Web Accessibility Initiative (WAI) ularly in the gaming industry. Yet recent availability 2004 Route des Lucioles BP94 of relative affordable processing power and high- F-06902 Sophia-Antipolis, France definition displays allows for an entirely different +1.617.500.5145 level of maturity. Existing standards, such as WebVR, indicate that sooner or later content will be accessed in multi-dimensional forms. Accessible Author Biography content does not rely on specific senses and access Shadi Abou-Zahra works with the W3C Web Acces- modalities, making it likely more apt for virtual, aug- sibility Initiative (WAI) as the Accessibility Strategy mented, and mixed reality. and Technology Specialist. He coordinates accessibility priorities in the W3C Strategy team, as well as Conclusion—Future-Proof Your international promotion and harmonization of web accessibility standards. Shadi also maintains WAI li- Content aisons with key stakeholders, including disability, re- Accessible content is more robust. It is usable by search, and standards organizations, as well as co- more audience in more situations, and is essential ordinates WAI outreach in Europe, accessibility for people with disabilities. Standards, resources, evaluation techniques, and European-funded pro- and technologies exist to make content accessible. jects on accessibility.

Fueling Your Future: STC Experience Builds Professional Leadership Skills Bethany Aguad, Crystal Brezina, Nick Ducharme, and Alex Garcia

Mentored by experienced professionals, the writers have taken on key roles within the STC Florida community. Our participation in the chapter's flourishing student mentoring and leadership development programs has accelerated our professional growth as well. The collaboration of experienced leaders with newer practitioners fosters leadership skills as the newer practitioners advance their careers and prepare to take on management roles in their companies and profession as well as within STC.

Student Mentoring Programs In its 15-year history, the STC Florida Chapter’s By Bethany Aguad, STC Florida Chapter Treasurer flourishing student mentoring program with UCF has been a key ingredient in our community’s continuing The STC Florida Chapter’s student mentoring pro- success and innovative programs. In essence, we gram pairs professionals in STC’s geographic com- have a steady pipeline of new talent to assume munities with student members at nearby universi- leadership roles in our chapter as veteran members ties. Mentoring programs benefit STC geographic approach retirement. The STC Florida Chapter’s communities, tech comm students, and working pro- highly successful student mentoring program brings fessionals alike. Beyond that, a successful student benefits all the way around—to student mentees, to mentoring program serves as a model for mentoring professional mentors, to the UCF tech comm pro- in the work place. gram, and to our STC community. As I prepared to embark on my career while com- The key ingredients for the program also apply to pleting my degree in technical communication, I was establishing a mentor-mentee relationship in the fortunate to have the opportunity to lead and take workplace: a skilled senior professional works with a part in the STC Florida Chapter mentoring program novice. Mentoring is more than cross training with the Future Technical Communicators (FTC) among peers, as it requires this senior/junior rela- student organization at the University of Florida tionship. It is important that the mentee not report to (UCF). I worked with my mentor, STC Fellow Dan the mentor within the organization (e.g., a supervi- Voss, who provided valuable guidance and experi- sor and a direct-report employee or a professor and ence as I entered the profession—an experience I a student in his/her class), because that compro- know he found immensely gratifying as well. mises the mentor’s critical role of confidante and advisor. A mentor-mentee relationship entails a special trust and clear communication, especially about how to deal with workplace dilemmas and pursue career advancement.

Figure 1. Student mentoring kick-off

7 Bethany Aguad, Crystal Brezina, Nick Ducharme, and Alex Garcia

Figure 2. One-on-one mentoring A successful relationship allows a mentee to in- Figure 3. STC Florida AdCo meeting crease his/her visibility in the profession, receive ca- Whether they are referred to as a “touch base” or an reer guidance and job search tips, polish special- integrated product team (IPT) meeting, frequent ized skills, and to enhance skills for career advance- meetings are common for many projects and most ment. Mentors gain personal satisfaction helping organizations. These meetings bring team or organ- others reach their potential. In the process, they ization members together to discuss status of active also enhance their coaching skills and gain expo- projects, plan upcoming projects, address ques- sure to new perspectives and new media. My options, and resolve problems. For STC communities, portunities within STC have not only served me well they are essential to growing from a small start-up in my career, they have also prepared me for my group to a flourishing organization with multiple next challenge as a candidate for the STC Florida committees and active and invested members pur- Chapter presidency for the upcoming chapter year. suing a wide range of professional development and educational outreach initiatives. AdCo Meetings As current secretary of the STC Florida Chapter and By Crystal Brezina, STC Florida Chapter Secretary as an instructional designer with Carley Corpora- tion, I have been to countless such meetings. As The STC Florida Chapter Administrative Council, or such, I feel it is safe to say they are paramount to AdCo, meets monthly in a quiet room in a local res- the success of an organization. That may seem like taurant with internet connectivity to allow virtual as an overemphasis on what appears to be a simple well as face-to-face participation. The meetings are status meeting, but one look at the several pages of open. Other chapter leaders such as committee minutes recording results of our AdCo meetings will managers, the newsletter editor, and the website indicate otherwise. Topics range from short status administrator join the elected officers of the Council. updates from committee managers to intense dis- Our monthly AdCo meetings are lively, enjoyable, cussions and decision making on a yearlong pro- and highly productive. ject. Although AdCo meetings and project meetings are The STC Florida Chapter’s AdCo meetings are simi- fundamentally for discussing tasks, there is always lar to the frequent meetings held during instructional room for a fun. That is why we hold our AdCo meet- design projects, in which designers and writers pro- ings at restaurants. The social setting gives mem- vide status on their portions of the project, while bers a chance to get to know each other outside of leaders and managers discuss how everything a solely professional setting. Members who are en- needs to fit together to create the final product. The couraged to mingle with each other before and after final products are our monthly educational pro- the meetings are more likely to be invested because grams, which require planning and execution; main- they do not view them as just business meetings. taining our regular communication media, which span traditional and emerging social media; and sustaining various ongoing initiatives such as our student mentoring program, our Active Membership

8 2018 STC Technical Communication Summit Proceedings Fueling Your Future: STC Experience Builds Professional Leadership program, our participation in the Society’s Commu- The STC Florida Chapter’s presentations for the nity Achievement Awards (CAA) program, and 2018 Summit represent the first application of our more. new “Passing the Torch” Leadership Development Program (LDP), which is designed to train “Rising You may be wondering how you can build and im- Stars” to assume formal leadership roles within the prove a chapter or project just with frequent meet- community. This much is true. Yet, the LDP is not a ings. The two most important factors in what makes one-size-fits-all solution. One individual might want frequent meetings effective are tracking the status coaching on how to think outside the box. Another of previously initiated tasks and planning for tasks to might not know how to properly delegate. Person- come. After all, it can be difficult to finish a project if ally, I hope this program will help me become more you don’t know it relates to previous tasks and how organized at work and at home. it currently stands. Providing the status of action items identified in previous meetings, especially if they lead up to larger tasks, is essential for all members to be on the same page. This also opens the floor for members to ask questions and seek guidance and feedback for the future. Once completed tasks have been addressed, we discuss upcoming tasks and decide how to go about completing them. Throughout the meeting, we brainstorm ideas on how to solve potential problems and how to go about completing a project. These discussions encourage members to participate and volunteer for tasks that may involve more than one individual or which can be divided up into smaller tasks. Figure 4. Planning at the Leadership Development After each AdCo meeting, all attendees should Program kick-off know the overall progress of current projects as well Are these various skills not all just aspects of lead- as what they can expect in the near future. To make ers we have already come to admire in our own sure everyone gets the word, I distribute detailed lives? Our chapter has identified 18 skills that pro- minutes on each AdCo meeting for review and ap- mote better leadership within STC, the workplace, proval at the next meeting. and beyond. I just named three: Creativity, Delega- tion, and Organizational Ability. We determine com- Leadership Development Program patibility between Rising Stars and coaches based on their confidence and experience levels in these By Nick Ducharme, STC Florida Chapter Communi- skills. I am certain my LDP coach, former Chapter cations Manager President Debra Johnson, will have much to teach me about organization and multi-tasking. At the surface level, “leadership” can be a divisive word. For some, the term might invoke an impres- Naturally, the exact number of leadership skills in sion of separation between the haves and the have- the world is subjective. The point is to have a frame- nots. work within which to evaluate your strengths and weaknesses in leadership. When you have a list of “I don’t possess the leadership gene.” skills in front of you and realize that you are actually “I desire the career path of a subject matter expert, quite strong in some of them, it frames the weaker not a manager.” ones in a context that seems much less insurmount- able than an ill-defined goal like “I want to be a bet- Do these sound familiar? They do to me, because I ter leader.” Our program, inspired by STC Fellow have said them. Mike Murray’s Fast-Start Leader’s Guide, starts The above quotes represent a traditional, one-di- from this philosophical foundation of philosophy and mensional view of what it means to be a leader. builds out from there to practical applications. However, it is a fallacy to treat leadership like a single skill when it is, in fact, a category encompassing several skills. In addition, a manager or supervisor is only one type of leader. We are all leaders in some ways.

2018 STC Technical Communication Summit Proceedings 9 Bethany Aguad, Crystal Brezina, Nick Ducharme, and Alex Garcia

its strategic goals and objectives for the upcoming chapter year and identifies the projects and activities we must execute to achieve those goals. Logistics: Since I was elected chapter president two years ago, I reinforced the STC Florida Chap- ter’s longstanding ’s relationship with the Technical Communication program within the English Depart- ment at UCF by holding our annual Leadership Re- treat at their Technical Communication Computer Laboratory. Logistics and meetings go hand-in- hand. You must secure a location that is appropriate for your team to work productively, and you must make your team feel comfortable (read: coffee and lunch). The private room at a local restaurant works well as you get both a place to hold your meeting and it comes with built-in catering. In the workplace, more often than not, at least part of your team will be traveling from out of town to kick off the project. Nevertheless, even if your customers reside down the hall instead of across the country, logistics are Figure 5. Coaches pass on skills to Rising Stars just as important. Acquire the meeting room, ensure As my career develops, I may indeed choose a sub- the audio/visual equipment is in working order, and, ject matter expert’s career path over that of a man- if the length of the meeting calls for it, coordinate ager. There is no harm in that. On the other hand, catering in accordance with your company or organ- as my confidence has grown in specific skills like ization’s protocol. At the very least, coffee service delegation, I have found myself graduating from and light snacks are a good idea. newsletter editor to communications manager. I might even be our chapter’s vice president next year! It is amazing how much of a confidence boost you can get just by honing a few core skills. My suggestion to other early and mid-career technical communicators is to look at our program’s framework and figure out what leadership skills you would most like to improve. Even if you cannot participate in a formal program like ours, I bet you can think of a colleague who would be a great informal coach in those areas. You will be Rising Stars in no time, my friends.

Leadership Retreat By Alex Garcia, STC Florida Chapter President Every project needs a kick-off meeting where the team gets together to get to know each other, clarify Figure 6. Alex presents the annual goals requirements, set expectations, and analyze metrics from previous projects. Think of running an STC Requirements and Expectations: As chapter chapter exactly like running such a project. The president, I arrived at our Leadership Retreats with STC Florida Chapter’s annual summer Leadership a PowerPoint presentation full to the brim with my Retreat provides a “post-mortem” on the previous vision for the upcoming chapter year. It was my Ad- year’s activities and serves as a kick-off meeting for ministrative Council and me to take that vision and the upcoming chapter year. At the annual summer pare it down to a manageable set of goals. By the Leadership Retreat, the STC Florida Chapter sets end of the day, through much negotiation, we had

10 2018 STC Technical Communication Summit Proceedings Fueling Your Future: STC Experience Builds Professional Leadership

the chapter year laid out. Remember, just like pro- professional growth in leadership roles on the job ject requirements, goals must be SMART: Specific, makes you a more effective leader within a profes- Measurable, Achievable, Relevant, and Time- sional association such as STC or wherever your bound. In my role as a Senior Technical Writer in life takes you. the Technical Publications Department at Lockheed Martin Missiles and Fire Control, I have learned that your contract document with your customer sets re- Conclusion quirements and expectations for deliverable publica- As you can see our experience in the STC Florida tions, including scope, schedule, format, and deliv- Chapter’s student mentoring and leadership devel- ery method. By the time you arrive at the project opment programs as well as in challenging new kick-off meeting with the customer, you should al- leadership roles within the community has directly ready have created a contract compliance matrix, translated into professional growth in our careers. It which ties each one of your contract requirements is a triple-win situation. Our companies benefit, STC to your project. The project kick-off meeting serves benefits, and we benefit. as one of the first opportunities to sit with your customer face to face and clarify contract requirements and scope. Be prepared to question your customer about any requirements that seem out of scope. Resources The contract is already signed—it is now time to execute it to the last possible letter. In support of this technical session on leadership opportunities and development, as well as a com- Metrics Analysis: One of the most useful parts of munity-building presentation at Leadership Day, we our Leadership Retreats is when STC Fellow and have compiled and posted to our chapter website STC Florida Chapter Active Membership Program an extensive toolkit that includes the guidelines and Chair W.C. Wiese presents a statistical recap of our administrative tools we use to sustain our student previous chapter year. This presentation, available mentoring and leadership development programs. It in an electronic toolkit as part of this Summit ses- also contains reference materials that provide in- sion, shows a year-for-year comparison of meeting sight into how we use our annual Leadership Re- attendance and membership engagement. It an- treat for strategic planning and our monthly AdCo swers the questions: “What worked and what did meetings for tactical execution of our goals and ob- not?” and “Which programs were successful, and jectives. Administrative tools and reference materi- which ones should we not repeat?” And, most im- als are also provided for other successful STC Flor- portantly, “Why?” ida Chapter initiatives described at Leadership Day, At work, this type of metrics analysis typically hap- including our scholarship programs and fund-raising pens after a contractual document is delivered, in a initiatives, our Active Membership program, and our Tech Pubs team-only meeting called a “post-mor- use of the Community Achievement Awards to pro- tem.” However, if there is comfort and rapport be- mote chapter development. It gives you a peek at tween your Tech Pubs team and the customer, they our latest and exciting initiative—building a may be included (especially if a follow-on contract is statewide STC community committed to the ad- about to start). After all the documents have been vancement of the technical communication profes- delivered, some questions that might be answered sion in the Sunshine State. The links to all of the re- at this meeting include: sources in the toolkit are available at Florida STC. • “What went right and wrong?” • “Was the original bid fair for both your Tech Author Contact Information Pubs team and the customer?” Bethany Aguad • “How much time did we spend on this pro- Technical Documentation Specialist ject?” Fiserv Lending Solutions • “How can we improve our process for the 600 Colonial Center Pkwy next project?” Lake Mary, FL 32746 321.213.2752 As you can see, participating in (or leading) an STC Leadership Retreat can prepare you to successfully maneuver within and even lead the various types of project meetings at work. At the same time, your

2018 STC Technical Communication Summit Proceedings 11 Bethany Aguad, Crystal Brezina, Nick Ducharme, and Alex Garcia

Author Biographies munication. He has served for three years as communications manager and newsletter editor for the Bethany Aguad is a technical documentation spe- STC Florida Chapter. Nick earned the 2017 Chapter cialist at Fiserv in Lake Mary, FL. In her six years President’s Award for his work in these areas. Over with STC, Bethany been a Sigma Tau Chi honoree, the past several months, he has passed on his received the STC Distinguished Service Award for knowledge and experience with chapter communi- Students (DSAS), and represented students on the cations and the Memo to Members newsletter to a Community Affairs Committee (CAC). She currently successor, Emily Wells, another recent UCF gradu- serves the Society on the Scholarship Committee ate and high-potential future chapter leader. In and Sigma Tau Chi and Alpha Sigma Committee. In 2017, he served as Nominating Committee chair for the STC Florida Chapter, she serves as treasurer, the chapter’s elections. This year he is running for website administrator, and co-manager of the Edu- the office of chapter vice president for the upcoming cation Committee. A graduate of the University of chapter year. Central Florida with a B.A. and M.A. in English— Technical Communication, Bethany has received Alex Garcia is a Senior Technical Writer at Lock- the coveted Melissa Pellegrin Memorial Scholarship heed Martin Missiles and Fire Control in Orlando, and Stuart Omans Award, both for Excellence in FL. He earned two concurrent bachelor’s degrees Technical Communication. With Dan Voss, she co- from UCF: in English—Technical Communication managed the STC Florida Chapter’s educational and in Space Engineering Technology. Alex fulfilled outreach initiative and student mentoring program a life goal as a systems engineer for the Space from 2012 to 2014, and she has presented on the Shuttle Program until he transitioned full time into benefits of student mentoring programs at Leader- aerospace technical communication. Throughout ship Day for two Summits. At the 2014 international the years, he has gained expertise in hardware doc- conference of the Sigma Tau Delta English honor umentation, proposal writing, and instructional sys- society in Portland, OR, she co-presented with Ra- tem design for a government audience. In 2005, chel Houghton on student mentoring programs and Alex was awarded the highly sought-after Melissa on careers in tech comm for English majors. This Pellegrin Memorial Scholarship for Excellence in led to an organizational alliance between STC and Technical Communication. An STC member for 13 Sigma Tau Delta at the executive level. Bethany co- years, he has held just about every role in the STC authored (with Dan Voss) Chapter 5, “Teaching the Florida Chapter. His relationship with the chapter Ethics of Intercultural Communication,” in the an- began as student president of the Future Technical thology of research articles Teaching and Training Communicators (FTC) organization at UCF. As a for Global Engineering, edited by Kirk St. Amant student member of the chapter, he served as co- and Madelyn Flammia, published in 2017. manager of the student mentoring program. As a professional member, he went to serve as Jaffe Crystal Brezina is an Instructional Designer at Car- Award Committee chair, editor of the Memo to ley Corporation in Orlando, FL. Crystal currently Members newsletter, chapter treasurer for two serves as the Florida Chapter Secretary and chair years, and then two terms as chapter president. For of the Community Achievement Awards (CAA) his leadership and dedication, the Society awarded Committee. Crystal is a recent graduate of the Uni- him the Distinguished Service Award for Students versity of Central Florida with a B.A. in English— (DSAS) in 2006 and the Distinguished Chapter Ser- Technical Communication. Crystal received the vice Award (DCSA) in 2013 and 2015. Alex pre- prestigious STC Distinguished Service Award for sented at the 53rd Annual STC Summit in Las Ve- Students in 2017. gas in 2006 reporting on his experience as a sum- Nick Ducharme is an Associate Configuration Ana- mer intern for Ball Aerospace in Colorado, and he is lyst (and Technical Writer) at Lockheed Martin Mis- looking forward to presenting in Orlando as presi- siles and Fire Control in Orlando, FL. He is an alum- dent of the hosting STC Florida Chapter in 2018. nus of UCF with a B.A. in English—Technical Com

Give in to the Power of the Dark Side: Marketing and TC are Converging! Bernard Aschwanden, STC Past President, Associate Fellow

We’ve come to think of it like this: content is content. Marketing and technical communications are generated for the same end users at different points in the product adoption life-cycle. The distinction between marketing communications and technical communications is far less pronounced than it once was. Managers sometimes see little difference in skill-sets and often put content creators together in one role or department—and maybe they’re right. During our careers we’re often dealing with a lot of technical content but also creating marketing communications; we’re in a good position to see how very little difference there might be between them. They’re both an always-on dialogue with the user, just at different points in the product adoption life-cycle. We’ll explore the audiences who consume content, ideas related to a seamless content experience, how both training and support factor into this, and talk about implementation ideas.

closer to (or further away) from family, or Overview any other compelling enough reason to con- We all generate content for the same audiences, sider your options. In other words, you rec- and those audiences always looking for something ognize a problem. more. The distinction between marketing and tech- 2. You start to research specific areas based nical communications is less pronounced than it has on proximity to or from specific things (work, been. Managers hire people with similar skill sets to schools, family), price (is it more, less, or create either type of content. Both business units the same price), neighborhood and ameni- have an an always-on discussion with users in ties to be found, number of rooms (more or online forums, or even in person. While we come in fewer), or other factors that impact your de- at different points of the product adoption lifecycle, cision. That is, you start to search for infor- we're all involved in two common goals; serving the mation to help make the decision. business in generating revenue, and helping the 3. Having collected information you begin to customer make the best business decision with the compare all the points in favor or against the information we provide. decision and evaluate your options. Perhaps you weigh things in a specific fashion (such as putting more emphasis on the schools in Tech Comm Must Be the area and a bit less on the size of the Part of Marketing house, or the proximity to work matters more than the final price) and you decide on Let's see how tech comm and marketing go to- the top option, as well as alternatives. gether based on a decision around housing that you may have had to make more than once in your life. 4. You sign papers. Your moving van (or Either renting or buying has the same overall pro- friends with pickup trucks and vans) arrives, cess. you load up, move to a new area, and settle in. The purchase decision is made and you 1. You recognize that you need to move for continue with your life. one of many reasons. A new job, changes 5. You start to review your decision and iden- to your relationship status, a child coming tify where you are (or are not) satisfied with into the family (or moving out of the house), the results. During this phase you may financial status change, needing to be

13 Bernard Aschwanden

make more purchases (a couch, pool, lawn you continue to deliver the experience that was ex- mowing service), re-evaluate your decision pected, and make it easy for them to be an advo- (is that school actually as good as they cate. Again, technical communications teams can said?), and compare the experience with al- work with support to identify ANY areas that need ternatives (maybe I should have moved into clarification, help rewrite workflows, change training the condo by the office, or the small house materials, update content, and ensure that ongoing on a large property in the country after all). discussions focus on the success of the customer. Reduce calls to the support desk, speed up resolu- In this example, and in almost any purchasing deci- tions to questions, and make it simple to find the an- sion, the consumer takes time to become informed. swers they need! This is defined through 5 key ideas, summarized from our example above. 1. Problem Recognition Content Convergence 2. Information Search Pre-sales: Marketing will provide enough info to in- 3. Evaluation and Selection of Alternatives form the consumers, and this content is often public. 4. Purchase Decision There is immediate feedback and often online discussions by existing customers with potential cus- 5. Post-Purchase Evaluation tomers. This should be where you learn what you Technical communications teams can play an active do well and where to improve. The discussion will and crucial role in three of these areas. often circle back to technical communications. Post-sales: Technical communications provides in- Information Search formation to help buyers to use products or services as intended to help them meet business goals in a When people are looking for information, they need usable and helpful way. This is the content that the substance that technical communications pro- should become part of the pre-sales message. Help vides. Marketing is great to build awareness of potential clients know how you help them every step products or services, and sales helps to close the of the way. Show them how you clearly explain deal. However, the core technical information in the ideas, procedures, or technical matters. Again, the "how to" or "why would I" or "reference and specifi- discussion should always circle back to technical cations" content is researched in detail by consum- communications. ers. The higher the purchase costs, or the bigger the corporate impact, the more time is spent in re- searching. Technical communications content is Seamless Content Experience crucial to informing the consumer at this stage. End users don’t think of it as “pre-” or “post-” sales, they think of the experience. They know it’s content. Evaluation and Selection of Alternatives They use it. It should work. They don't care about At this point the potential customer is reviewing which team "owns" the materials, or who they talk to what you offer and comparing it with what the com- on the way to the final decision. Content should de- petition offers. If you cannot clearly define your liver the same experience from start to end. If they value proposition, the methodology that you follow search, they should be able to search all your con- to implement a solution, or give clear specifications, tent. If you collect metrics on search, everyone then it's very simple to get bumped from the discus- should be involved in improvement based on the sion. That information comes from technical com- metrics. Always remember it's one customer. munications teams. Go Further Post-Purchase Evaluation Why stop at tech comm and marketing? Incorporate Once a purchase is finalized, ensure you provide sales, training, support, and any other division that great post-purchase support. Help customers de- interacts with the customer. Provide complete sup- cide your product or service has longer term value, port from start to end. Customers don't care what provide top notch support, remove obstacles from department has access to what content. They want usability, and make them glad they picked you. En- things to work, and when it won't work, they want sure the answers they need are simple to find, that easy to find answers.

14 2018 STC Technical Communication Summit Proceedings Give in to the Power of the Dark Side: Marketing and TC are Converging!

Conclusion Sharing content is invaluable as assets created by Author Contact Information one team should be reused where applicable. Don’t Bernard Aschwanden write it twice (or more) and in different ways. When President anyone updates content, everyone should benefit. Publishing Smarter Edit, review, approve, and translate your content. www.publishingsmarter.com Once. Then share. [email protected] You need to manage content as a business asset and show good information governance. Work with Author Biography multiple teams to intelligently meet the needs of the customer. All departments in a well managed busi- Bernard helps companies generate revenue by im- ness should be working with a robust content strat- proving content creation, management, and distribu- egy that unifies the message you deliver. tion workflows. He is the founder of Publishing Smarter (a company of content professionals work- A consistent user experience of content, no matter ing with strategy, implementation, and communica- where the end user is in the product adoption lifecy- tions), an Associate Fellow of STC, and a Past cle, just makes sense. Let customers flow seam- President of STC. Bernard has helped hundreds of lessly from one type of content to another, both companies implement successful content driven so- carefully aligned with the business cases and goals lutions. He is focused on publishing better, publish- of the consumer. ing faster, and publishing smarter.

Plan for Tomorrow: Project Management and Technical Communications Fundamentals Bernard Aschwanden, STC Past President, Associate Fellow

Writers are involved in project management. From the smallest piece of content (maybe just a review of a letter) to the most complex content going (documenting an airplane, drug, electric car, government policy, software manual, medical device, or any other information) we manage scope, schedule, budget, quality, risk, stakeholder input, and so much more. Isn’t it about time we leveraged the best practices of project management to deliver the best documentation we can? Learn to manage projects better by knowing more about the core components of a project. Identify what these mean for tech comm. Know the 10 knowledge areas, and understand of how they relate to every single tech comm project we work on. Better documentation through better management of our work. Sounds easy, right?

The exploration of a Component Content Man- Overview agement System (CCMS) for an improved busi- There are best practices defined in the context ness process, the creation of a new documenta- of Project Management. Each of these can be tion set for a product, the development of a way applied in some way within the field of technical to share content beyond a traditional writing communications. While I'm not a project man- team—all are projects. ager, certified as one, or even play one on TV, I These projects must be expertly managed to do have to apply these practices when imple- deliver on-time, on-budget results. Again, ac- menting solutions with clients. Projects are de- cording to PMI, project management is the ap- fined by PMI (Project Management Institute) as plication of knowledge, skills, tools, and tech- "a temporary endeavor undertaken to create a niques to project activities to meet the project unique product, service or result (Project Man- requirements. agement Institute, 2018)." Project management knowledge draws on 10 • A project is temporary. It has a clearly areas and we'll explore these by defining what stated beginning and end in time, with a PMI says they are, and then quickly outlining specific scope and set of resources. how these apply to your job. • A project is unique. It's not a routine op- eration (like publishing, or a review cycle), but a specific set of operations de- Scope Management signed to accomplish a singular goal … is primarily concerned with “defining and con- (like creating a User Guide or transform- trolling what is and is not included in the project ing a written PDF document to an inter- (Project Management Institute, 2018).” active eLearning delivery. Projects are made up of teams who may not usually work together, but collected with the goal of a finished deliverable.

16 Plan for Tomorrow: Project Management and Technical Communications Fundamentals

Your job: Ensure the project includes all the Your Job: Determine what tools or training to work required, and only the work required, to purchase, what additional hardware is needed, complete the project successfully. and whether a consultant is needed and who to hire; determine timing; follow-up after delivery. Time/schedule Management Human Resource Management … is primarily concerned with accomplishing “timely completion of the project.” … is primarily concerned with “processes that organize and manage the project team.” Your job: Identify activities, sequence them, estimate resources required to complete them, es- Your job: Ensure early involvement during the timate time requirements, and schedule them. planning process, identify project roles and responsibilities, clarify reporting structure, find bodies to do the work, build/improve on existing Cost Management skill sets (provide training), track performance. … is primarily concerned with “planning, esti- mating, budgeting, and controlling costs so that Communication Management the project can be completed within the ap- proved budget.” … is primarily concerned with ensuring the “timely and appropriate generation, collection, Your job: Estimate cost of resources for project, distribution, storage, retrieval, and ultimate dis- budget these across activities/work packages, position of project information.” and influence those factors that create cost vari- ances/budget changes. Your job: Determine who is a stakeholder and what info they need, distribute required information to stakeholders, report on status and Quality Management performance, resolve any stakeholder issues. … is primarily concerned with the project satis- fying “the needs for which it was undertaken.” Integration Management Your job: Identify which quality standards are … is “making choices about where to concen- relevant to your project, apply them, and moni- trate resources and effort on any given day, an- tor project results for compliance. ticipating potential issues, dealing with these issues before they become critical, and coordinat- Risk Management ing work for the overall project good.” … is primarily concerned with risk “identification, Your job: Pulling together the activities from all analysis, responses, and monitoring and control the other knowledge areas to make the project a on a project.” success. Your job: Determine which risks might affect the project, prioritize them based on probability and Stakeholder Management impact, analyze their effect, develop options and … is “a strategic discipline that successful pro- actions if they occur, monitor them, and execute ject managers use to win and sustain support response plans if required. for their projects from others, both internal and external to their project and to the project's or- Procurement Management ganization.” … is primarily concerned with the purchase or Your job: Ensure you know who is impacted, acquisition of “products, services, or results within and outside your company, and keep needed from outside the project team to perform them “looped in” on what is happening in all the work.”

2018 STC Technical Communication Summit Proceedings 17 Bernard Aschwanden

areas. Read more: https://www.pmi.org/learn- Author Contact Information ing/library/stakeholder-management- plan-6090. Bernard Aschwanden President Publishing Smarter Why Projects Fail www.publishingsmarter.com [email protected] Top 5 classic mistakes: 1. Poor estimation/scheduling: 54% Author Biography 2. Ineffective stakeholder management: Bernard helps companies generate revenue by 51% improving content creation, management, and 3. Insufficient risk management: 47% distribution workflows. He is the founder of Pub- 4. Insufficient planning: 39% lishing Smarter (a company of content profes- 5. Short-changed quality assurance (not sionals working with strategy, implementation, building in enough time): 37% and communications), an Associate Fellow of STC, and a Past President of STC. Bernard has helped hundreds of companies implement successful content driven solutions. He is focused on publishing better, publishing faster, and pub- Resources lishing smarter. Forman, James B., and Richard Discenza. “Got Stake? (Holder) Management in Your Project.” Project Management Institute (2012). https://www.pmi.org/learn-ing/library/ stakeholder-management-plan-6090.

References "What Is Project Management?" Project Management Institute (2018). https://www.pmi.org/about/learn-about- pmi/what-is-project-management.

Teaching Technical Writing to Engineers—What Works? Noel Atzmiller

Teaching technical writing to engineers can be challenging. These highly intelligent individuals require an approach that goes beyond grammar rules and guidelines. Training session content and techniques must focus on the engineers’ common characteristics. Experiences from leading multiple training sessions to engineers and their feedback have revealed some lessons learned to facilitate this approach. These lessons are applicable in technical writing training sessions for many documents.

Experience and Feedback Yield Les- Lessons Learned—Before the Ses- sons Learned sion One of my job responsibilities is to provide technical writing training to the engineers at Baker Hughes, a Lesson No. 1—Analyze the Audience. GE company (BHGE). To accomplish this, I prepare and present training sessions at various BHGE of- Although this lesson might sound too elementary, fices. you need to determine the engineers’ common characteristics and their specific training needs. Be- Over the last four years, I have led 54 training ses- fore my training sessions, I accessed websites and sions at BHGE international offices in eight coun- read books that described engineer characteristics. tries and at several offices in the continental US. I also interviewed several engineers with whom I The majority of these sessions were instructor-led in worked. Eventually, I identified five common charac- a classroom setting. Participants in these sessions teristics. I then determined what the training materi- attended to learn information that would help them als must provide for these characteristics. write abstracts and technical papers for oil and gas conferences. Engineer Training Materials Most session participants were degreed, profes- Characteristics Must Provide: sional engineers in many areas of expertise. Sev- eral other participants held advanced education de- Detail-oriented Task details grees. All those present, though, exhibited many common characteristics. Consequently, I regarded Logical Concise, logical steps all participants as “engineers”. Focused Rapid information display At the conclusion of each session, the engineers filled out feedback forms. These forms provided the Analytical Analysis opportunities engineers with the opportunity to evaluate the session and to make suggestions. I gathered the forms Organized Orderly, structured information and analyzed the information on them. From the feedback forms and my session experi- Table 1. Engineer characteristics and training mate- ences, I identified ten “Lessons Learned.” These rials lessons are not specific to the documents discussed Next, you must determine the specific training con- in my training sessions. In addition, the lessons are tent that the engineers need for their document(s). I not specific to the oil and gas industry. I offer these conducted several conversations with engineers lessons for your consideration because they are ap- and discovered that many of them were very con- plicable in training sessions for many documents in cerned about writing an abstract and a technical pa- many industries. per. Several engineers had little/no knowledge of

19 Noel Atzmiller

what an abstract and a paper should (or should not) The engineers reacted favorably to these collected contain. Consequently, I determined that the engi- materials and stated this in their feedback forms. neers needed accurate explanations about these This technique appealed to the engineers’ charac- documents as well as tips and suggestions on how teristic of being organized. to write them. I also discovered that many engineers had not writ- Lessons Learned—During the Ses- ten a lengthy technical document since their college days. Consequently, common writing mistakes sion would be a significant problem. The engineers needed a refresher on grammar, punctuation, capi- Lesson No. 4—Begin the session by ask- talization and other topics. ing questions. Your audience analysis might reveal similar con- Most sessions had between 15 and 20 engineers. cerns and training needs. Take the time to identify Few engineers knew others in the session; it was “a what your engineers need and determine what your room full of strangers.” Asking questions was useful materials must provide to supply it. to “break the ice” and to obtain some information about the engineers’ expectations for the training. Lesson No. 2—Produce content that sup- My first question was “Who has written an abstract plies what they need, designed for their or a paper?” To those who indicated they had done characteristics. this, I then asked, “Was this easy or difficult, and After you determine what your engineers need, you why?” I commented on their answers and explained must then produce training content for their charac- the challenges in writing these documents. teristics. For my training sessions, I developed a Next, I asked, “Who has read a technical paper re- simple agenda that addressed the main topics. cently?” Again, to those who indicated they had When you develop your training session agenda, done this, I asked, “Was the paper well written, or strive for a similar approach. did it contain some issues?” I provided my com- Example training session agenda: ments and emphasized how these documents required preparation and quality writing. • Writing a Good Abstract I then re-assured the engineers that the session • Learning from Other Abstracts would provide information they could use when writ- • Writing a good Technical Paper ing their abstracts and papers. Develop your ques- • Avoiding Common Writing Errors tions to reflect on the document(s) that your engineers will produce. This agenda appealed to the engineers’ characteristics of being logical and organized. I received many favorable comments about the agenda in the feed- Lesson No. 5—Describe the session mate- back forms and during the training sessions. rials. After concluding the “ice breaker” questions, I drew Lesson No. 3—Produce organized session the engineers’ attention to the session materials. I materials. briefly explained the contents of the folders/binders and informed the engineers how we would use the Nobody likes confusion in a classroom—especially materials in the session. This activity greatly re- engineers. Organized training materials will reduce duced confusion when I asked the engineers to find confusion and benefit your session. particular items during the session. A side benefit I produced the session materials and organized was the opportunity for me to explain how the engi- them in folders or binders. I then placed the materi- neers could use the material when writing their ab- als on the tables or desks before the engineers ar- stracts and papers. rived. As the engineers entered the room, they sat This technique appealed to the engineers’ charac- down and immediately began to review the materi- teristics of being organized and detail-oriented. als. This technique removed the task of requiring the engineers to pick up the materials upon entering the room.

20 2018 STC Technical Communication Summit Proceedings Teaching Technical Writing to Engineers—What Works?

Lesson No. 6—Use various teaching read the document, I then pointed out specific ex- methods. amples of good writing and explained how these could be repeated in their documents. The engi- To maintain the engineers’ interest and to ensure neers appreciated seeing well-written documents, they understand the session information, use vari- understanding what made them high quality, and ous teaching methods. Here are some methods that learning how they could write similarly. This tech- I used: nique appealed to the engineers’ characteristics of • Group the engineers. In some sessions, I being analytical and detail-oriented. organized the engineers into groups of two or three. I then directed each group to ac- Lesson No. 8—Let the engineers critique cess an exercise sheet in their training ma- poorly written documents. terials. After giving them time to perform the exercise, we discussed their answers and I In one of the in-session exercises, I asked the engi- made some suggestions for improvements. neers to review an abstract that contained many er- • Arrange for a guest speaker. On occasion, rors. I mentioned that the abstract was produced by I scheduled an engineer, who was an expe- a competitor company, and I then instructed the en- rienced writer, to speak at the training ses- gineers to identify and mark the errors. The engi- sion. This person was also a member of neers found this exercise particularly enjoyable. Af- several conference technical program com- ter about 10 minutes, I solicited their comments and mittees that reviewed abstracts and deter- the errors they found. I then described how the en- mined if they would be good papers. The gineers could avoid these errors on their docu- engineers appreciated the candid tips, sug- ments. This technique appealed to the engineers’ gestions and cautions provided by the guest characteristics of being analytical and detail-ori- speaker. ented. • Use humor to provide information. Humor can be a good “change of pace” for the Lesson No. 9—Provide compliments and training session. I displayed a short, humor- express appreciation. ous presentation titled, “Ten Writing Errors to Avoid”. It generated laughter and pro- During the in-session exercises and at appropriate vided instructions on how NOT to write. times during the session, I provided sincere compliments to the engineers. At the conclusion of the • Provide PowerPoint presentations. The session, I expressed my appreciation for the time engineers readily accepted this teaching they committed. Many engineers had delayed work method. However, I discovered that the in- on their projects, and I recognized this. terest/attention level of most engineers dropped significantly after about 25 minutes. This brings me to the final lesson learned—one that Consequently, I limited my PowerPoint applies after the session concluded. presentations to 30 minutes or less. • Use in-session exercises. For each train- Lessons Learned—At the End of the ing session, I produced one or two exercises. Again, in response to the engineers’ Session interest/attention level, I designed each exercise to last approximately 25 minutes. Lesson 10—Ask for feedback. All these methods appealed to the engineers’ char- Feedback is important for evaluating any training acteristics of being focused and analytical. session. However, the engineers who attended my training sessions were not inclined to spend much Lesson No. 7—Explain the details of well- time providing this feedback. To accommodate this written documents. situation, I designed a one-page feedback form and placed it in the session materials. During my training sessions, I asked the engineers to access the sample of a well-written document I asked the engineers to access the form from their from their training materials. After the engineers training materials and to fill it out. I encouraged them to provide their evaluation of the session and to write their comments and suggestions. Positive

2018 STC Technical Communication Summit Proceedings 21 Noel Atzmiller

evaluations dominated the forms, and there were Sagan, Jayme. Lessons My Cat Taught Me About many useful comments and suggestions. Instructional Design (Proceedings, STC Summit Conference, 2016). Produce your feedback form so the engineers can easily indicate their evaluation, comments and sug- Weiss, Edmond. Writing Remedies: Practical gestions. Exercises for Technical Writing (Phoenix, AZ: Oryx Press), 1990. Weatherford, Darla-Jean. Technical Writing for Conclusions Engineering Professionals (Tulsa, OK: PennWell Press), 2017. Teaching technical writing to engineers can be challenging, but these ten lessons learned can help. In summary, I suggest that you Author Contact Information • Determine the engineers’ common charac- Noel Atzmiller teristics. Manager, Technical Publications Baker Hughes, a GE Company • Identify what they need to produce their document(s). 17021 Aldine-Westfield Rd. Houston, TX 77073 • Provide content and techniques that supply 281.731.4697 what they need, designed for their characteristics. Author Biography Noel Atzmiller began his 35-year career in technical Resources communications in the petrochemical engineering and construction industry. During his career, he has Berger, Robert. A Scientific Approach to Writing for produced documents for many industries including Engineers and Scientists (Hoboken, NJ: Wiley natural gas transmission, I.T. and oil/gas. Noel has and Sons, Inc.) 2014. also authored several articles that have been pub- Finkelstein, Leo. Pocket Book of Technical Writing lished in corporate and oil/gas trade publications. In for Engineers and Scientists (New York, NY: 2010, he was awarded the Best of Show at the STC McGraw Hill), 2005. International Communication Summit in Dallas, Green, Anne. Writing Science in Plain English Texas. His award-winning document chronicled the (Chicago, IL: The University of Chicago Press), first 75 years of Baker Atlas, a previous division of 2013. Baker Hughes. Irish, Robert, and Myra Poe. Writing in Engineering: Noel currently works at Baker Hughes, a GE Com- A Brief Guide (London, England: Oxford pany (BHGE). In his position as Manager, Technical University Press), 2016. Publications, Noel helps BHGE authors by providing Laplante, Phillip. Technical Writing: A Practical many services including document editing, leading Guide for Engineers and Scientists (Baton training for writing conference abstracts and papers, Rouge, LA: CRC Press), 2012. and providing user support for the corporate docu- McMurrey, David. “Online Technical Writing Free ment management system. Online Textbook for Technical Writing.” https://www.prismnet.com/~hcexres/textbook/. Nathans-Kelly, Traci, and Nicometo, Christine. Slide Rules (Hoboken, NJ: John Wiley & Sons, Inc.), 2014. Neuen, Sue, and Tebeaux, Elizabeth. Writing Science Right: Strategies for Teaching Scientific and Technical Writing (New York, NY: Routledge Publishers), 2018. Rosenberg, Barry. Spring into Technical Writing for Engineers and Scientists (Upper Saddle River, NJ: Addison-Wesley Publishers), 2005.

LIGHTS, CAMERA, ACTION: Exploring Video Basics for Non-Production Professionals Darcy Beery and Stacy Barton

Given the choice between finding the user manual or googling a short, instructional video on YouTube many users today would prefer to both hear and see the information being presented, especially younger generations who have been raised with technology. The basic concepts of video production need no longer be shrouded in the mysterious aura of Hollywood as consumer technology has become both cost effective and highly professional. If you, or your company, have been toying with the idea of producing videos for clients or customers, but have fretted about the costs or effectiveness of this delivery method, take heart it is now easier and more anticipated than ever before.

One of the challenges in delivering information to just having a dominant style, we have a mix of your target audience is identifying who they are and styles and can actually switch styles in different situ- understanding how they have been molded to con- ations or enhance our use of a style with more prac- sume media. We will briefly look at the generational tice (Advanogy.com). preferences for learning and the corresponding as- Warren’s article on learning differences concludes pects of messaging that can be addressed with that “a major factor in…learning preference is the video content. Fig. 1 is a simplified version of my predominant educational trends during a student’s prior research on generations which we will use as formal education” both in teaching style and access a basis for our discussion (Beery). to technology (Warren). She demonstrates the learning styles graphically as seen in Figures 2-4. Generational Preferences & Learn- Fig. 2 shows the Boomers very linear learning expe- ing Styles rience consisting of lectures and reading books. A generation’s learning style has a large impact on their informational preferences. Most people are familiar with the basic four (visual, aural, verbal and physical), but many may not realize that, more than

Figure 1: A generational timeline based on events specific to the culture within the United States

23 Darcy Beery and Stacy Barton

learning styles of multiple generations. Whether you are working from a formal classroom or conference Figure 2. Linear learning style of Baby Boomers setting where you can record and upload the message or you’re trying to engage in more interactive Figure 3 demonstrates Gen Xers’ who moved to- content by embedding areas for comments/ques- ward a mix of lectures and small group activities. tions or content quizzes, or you’re using self-directed learning with on-demand self-paced sessions or even on-demand, informal knowledge sharing like providing a quick start page, FAQ’s or reference material, video allows for success with all these scenarios (Panopto). In fact, 90% of Gen Z and 78% of Gen Y report utilizing YouTube™ several times a week/daily for accessing instructional or content information; this compares with 66% for Gen X. However, if we look Figure 3. The Gen X structure learning at only daily use, Gen Z reports 70% usage, Gen Y becoming fluid 49% and Gen X 35%. This displays a future trend moving towards increased generational video con- Figure 4 displays how Gen Ys and Millennials fur- sumption for accessing information (Bazilian). ther moved away from a group learning paradigm with their increased use of available technologies. With proper planning, today’s video technology can allow for content reuse taking one simple video production project and allowing the information to be accessed in ways which allow individuals in your target audience to best meet their needs, or to “self- serve” (Hoffman). Using chapters and indexes during the editing process allows Boomers to access the content sequentially and Gen Xers to choose a section of interest and drill in for deeper content; while Gen Y’s/Millennials can enjoy the content in a completely non-linear fashion – bouncing around as they need to. This modular and expected style of modern video production can increase your reuse of Figure 4. Flexible learning path afforded Millennials content impacting your ROI. and Gen Y’s with technology As Gen Z enters the workforce with an increased Corporate Myths, Misconceptions & comfort-level with technology, there is an expectation of unlimited access to information and with the ROI ability to change focus quickly they are very com- A typical conversation about producing corporate fortable with independent learning. video content commonly runs into a number of barri- When working with a large or mixed group you need ers, specifically cost and effectiveness. You will of- to make sure you engage each style. Visual learn- ten hear the argument that it is too hard—the cur- ers can benefit from graphics as they display the rent staff can’t do it, it’s too expensive—not only in connection of ideas and data. Aural learners need the original cost of creation, but with updating and to speak so include some audience questions in maintenance as well, and, lastly, that it is not neces- your presentation or a Q&A time at the end. Verbal sary—that current content consumers don’t need or learners, also known as the reading/writing style, want video. This assumes they’ll continue to search prefer handouts and a section to take notes in help- traditional documentation as they always have, ing them stay engaged and physical learners are however we believe this trend is changing so let’s hands-on so include some in-session activity or ex- examine some potential ROI. ercise for them (Nakano). In a blog from Panopto, a recognized leader in Video is the platform that offers the greatest flexibil- video content management, it is point out that vid- ity for scaling a message and meeting the diverse eos are used to supplement and scale Learning and

24 2018 STC Technical Communication Summit Proceedings LIGHTS, CAMERA, ACTION: Exploring Video Basics for Non-Production Professionals

Development programs. Videos are particularly use- • WHY - a clear objective is articulated to de- ful for “delivering more engaging training to global, termine factors that can be measured for regional and front-line offices, reducing costs asso- success ciated with travel, events and AV production and • HOW - the big-picture content—will you use curating and saving institutional knowledge to miti- SME interviews or will an engaged em- gate expertise lost due to turnover” (Panopto). ployee show the process just as well. (Though experts are helpful, seeing is much UX: Concept to Creation stronger than just hearing so consider using that to your advantage.) Video production fosters clear and demonstrable • WHAT CONTENT - engage with some basic concept comprehension for end users and provides production elements to successfully convey definable benefits for the company by producing ac- your vision to your cast and crew ensuring cessible, updatable content in a recognizable pat- that you have met your objective by thinking tern ensuring enrichment of the UX for all targeted through everything you want your audience audiences. to see and hear. Be very specific with this In the article “Directing the Content Experience,” the step. author contends that you must “deliver your infor- Successfully working through this process will build mation (onboarding materials, training guides, user a solid concept, whether for micro-content or an en- manuals, break fix articles, and even best practices) tire process overview, which ensures that the tar- into a tailored form that considers the end user’s geted message reaches the target audience. Now needs (both what they want and on what device you will need to consolidate all your ideas into a they want it)” (Hoffman). script format. The A/V (audio/video) script is probably the easiest for non-production personnel to use. Concept Creation In order to create a concept which targets your mes- Basic A/V Script sage for your audience there are a few helpful steps A dual column or A/V script as we see in Fig. 5 is to consider. Friedmann espouses seven steps for a the basic format that allows beginners to make sure creative concept in his book, Writing for Visual Me- all their key points and shots are included. All the dia, however we can achieve our goal with some video instructions are in the left column and the cor- modification of the first five: what need, who, why, responding audio instructions are on the right. how, and what content (Friedmann). • WHAT NEED - a clear identification of the Stages of Video Production problem, process or policy to be addressed • WHO - an evaluation of the target audi- Creating a script is the first step in the video produc- ence(s), taking into account demographic tion process, followed by pre-production when or- factors ganization and logistical planning tasks are

______INT. CONFERENCE ROOM-DAY

PEOPLE MILL ABOUT BEFORE A V/O PANEL CHAIR: If I could have everyone’s atten- PRESENTATION STARTS. tion please …. let’s take our seats now, thank you. ______Figure 5: A brief sample of an A/V script format

2018 STC Technical Communication Summit Proceedings 25 Darcy Beery and Stacy Barton

reference on-set; a checklist of sorts. Other pre-pro- completed. Production begins with the recording of duction tasks include casting on-screen subjects, the first ‘shot’ and concludes with the last. Post-pro- scouting a shooting location, gathering production duction, commonly called ‘editing’, involves se- equipment, and scheduling the ‘shoot’ (or alter- quencing the various shots, containing both audio nately hiring a video professional). and video ‘tracks’. From there, graphical and text elements like titles, websites and logos are created, and effects are added. Adjustments are made until Casting the project looks and sounds exactly as the maker Featuring the right ‘talent’ is crucial in communi- intends. The finishing stage ends with ‘exporting’ cating effectively with a viewer. Oftentimes, the the video to a self-contained movie file. A video dis- technical content expert can confidently speak with tribution plan can include online Internet delivery integrity from an informed point-of-view on the topic. through content-streaming sites like YouTube™, a But, what if they aren’t relatable on-screen? What if private website, or even DVD delivery. they mumble or fidget? What if nerves prevent a confident delivery? On-screen communication is as Pre-Visualization much about visual approachability and aural clarity as it is about information. Actors can be an alterna- The choices made in the writing stage will ultimately tive when real people fail to perform. Whoever ulti- dictate production workflow. In fact, an A/V script mately interfaces with the viewer, what’s most im- will go further and specify framing focal-length, also portant is effective communication, however that called ‘shot size’, and camera movements like ‘pan’ can be achieved. or ‘tilt’. Shot planning requires pre-visualization; seeing the video play out beforehand in the mind’s- eye, gauging the most effective visual communica- Choosing a Shooting Location tion to carry the intended message to the viewer. A good location’s aesthetic will be characteristic of There are some important questions to ask in pre- the subject matter. Cooking takes place in the visualization. kitchen for example, and that kitchen will be telling of the subject who inhabits it, be it a suburban Shot Planning housewife or a group of college co-eds. The shot background should be free of unauthorized trade- Is some area around the subject needed, to include marked logos and copyright-protected imagery and other content? If so, a long-shot, abbreviated LS, sounds. There will be electrical outlets to support frames the full subject head-to-toe with some setting production equipment requiring power, like lighting visible for context. Is a closer shot of the subject fixtures, an AC adapter-connected camera, or bat- and their actions more appropriate? A medium-shot, tery charger. The location should be isolated for abbreviated MS, is framed from the waist-up for a clean dialog recording, free of mechanical hum from clear view of expression, gesture, and perhaps nearby machines or appliances. Since hard sur- hands at work. A medium-shot gives the viewer a faces like walls, countertops, tile floors, and metal sense of being face-to-face with the subject, effec- furniture can cause sound reverberation, resulting in tively conveying dialog. A medium-close-up (MCU) an echo-like audio quality, locations with sound ab- feels even more intimate, framing only the head- sorbing carpet or curtains are recommended. Out- and-shoulders. Will a magnified detail help to clarify side sound interference including airplanes, auto- a point, process, tool, or product not sufficiently visi- mobiles, and foot traffic can ruin an otherwise per- ble in wider shots? A close-up (CU) or even an ex- fect location. Finally, a space where recording is treme close-up (ECU) brings the viewer in for a bet- less likely to be interrupted is ideal. ter view. In a demo involving small adjustments, these shots help to clarify details to the viewer. A close-up framing only a subject’s face magnifies the Outsourcing vs. D.I.Y. emotion in their expressions. It is a dramatic shot According to Jake LeVoir at SlateandMain.com, out- rarely appropriate in technical videos. sourcing production of a short corporate video can run from $500 to $2,500. Most videographers, how- Other Pre-Production Tasks ever, charge a ‘day rate’ rather than a flat fee. True cost, of course, is dependent on market rate and A ‘shot-list’, created from the A/V script, lists the task at hand, and can vary widely. Although, if doing shots to be collected in production for convenient

26 2018 STC Technical Communication Summit Proceedings LIGHTS, CAMERA, ACTION: Exploring Video Basics for Non-Production Professionals

it yourself is of interest, modern advances in pro- Audio Recording Tips duction equipment encouraged by market competition have brought video quality up and prices down. Avoiding bad sound pitfalls when recording is imper- It’s affordable nowadays to buy the video camera, ative. Microphone interference caused by rubbing, tripod, microphone, lighting fixture(s), and editing handling, or low-battery hiss, undesired sound- software needed to create high-quality, professional bleed, background hum, ‘room tone’ airiness, rever- videos that consumers of today expect. And, it’s beration, or even mumbling talent will render other- easier than ever to acquire the technical know-how wise good video unusable. Microphone choice and to do it yourself. proximity are key to recording clear, isolated dialog. If the subject is stationary, a ‘lavaliere’ mic clipped to their lapel will work great. If they’ll move around, Video Camera Considerations there’s more than one subject, or other ambient All new video cameras today record in widescreen, sounds will need to be heard, a directional ‘shotgun’ high-definition, ensuring the image resolution will be mic pointed at the subject(s) will capture the audio high-quality. Consumer camcorders are economical, best. ranging from $200–$1,000 new. But, they may not achieve professional results in all cases. Prosumer camcorders can generally achieve quality results Post-Production with some manual adjustment, and go for $1,000 Today, there are many affordable options for editing and above. Logically, professional camcorders are videos. The popular YouTube™ platform offers the more complicated and expensive ($3,000+), but do functionality to cut video clips together for free. Ap- achieve the best results. ple’s cross-platform QuickTime™ application (pre- installed free on new Apple computers) facilitates Affordable DSLR Options video clip trimming, splitting, combining, and even some simple effects and graphics. More ambitious Popular today are DSLR cameras. Although opti- editors can subscribe to Adobe Creative Cloud™, mized for still photography, they also record HD offering users access to all Adobe creative software video. DSLR cameras can be purchased by body for one low monthly fee, including the popular only, with detachable zoom lens, or in bundle op- Adobe Premiere Pro CC™ video editor. tions that add a directional video-mic for improved in-camera audio recording, the SD card to store the media, or even an extra lens. Canon’s Rebel series D.I.Y. Training Resources DSLRs are a great option for beginners, the latest Endless resources for acquiring video skills are model being the Canon EOS Rebel T7. DSLR cam- available online. Subscription-based learning plat- eras can achieve cinematic results with the right forms like Lynda.com™ feature tutorial videos in- lens, and some, including the Rebels, cost less than structing on all stages of video production. Adobe $1,000. Creative Cloud™ provides free video tutorials for all of their software on the help-x.adobe.com website. Cinematography Tips They also host live demonstration events and workshops with reputable media-makers, available to Before pressing record, ask yourself some im- stream online or attend on-location around the portant questions. Is the lighting flattering to the country. subject? Is the framing professional? Leaving the perfect amount of ‘headroom’ above the subject, placing them to one side of the frame along the Conclusion ‘rule-of-thirds’ gridlines, and ensuring enough ‘look- Yes, of course the rumors surrounding Hollywood’s ing space’ in the direction they are facing for visual hiring of hundreds, spending exorbitant amounts, & psychological balance; these are some basic and taking months or years to complete a produc- rules to professional cinematography. The videogra- tion are definitely true. But basic video production, pher’s goal is to get good ‘coverage’ by recording a on the other hand, is a step-by-step process that variety of angles and focal lengths that will best tell can yield effective results with relatively small in- the story. vestment. Considering the reach potential of online platforms like YouTube™, where it’s free to upload and convenient to access millions of videos, the

2018 STC Technical Communication Summit Proceedings 27 Darcy Beery and Stacy Barton

time is now for technical communication to meet 2017) 12. http://www.adweek.com/tv- consumers where they are online, with informative video/infographic-how-gens-x-y-and-z- videos further connecting purchasers with the prod- consume-video-content/. ucts and companies they love. Beery, Darcy. Utilizing Classroom Diversity to Enhance Multi-Generational Learning. (Proceedings, Hawaii International Conference on Arts & Humanities, 2018). Resources Panopto. “Are You Ready to Support 4 Generations Adobe.com/CreativeCloud (19 April 2018). of Learners?” Panopto.com (5 May 2017). https://www.adobe.com/creativecloud.html. https://www.panopto.com/blog/are-you-ready-to- support-4-generations-of-learners/. BHPhotoVideo.com (19 April 2018). https://www.bhphotovideo.com/. Friedmann, Anthony. Writing for Visual Media Author Contact Information (Fourth ed). (New York, NY Focal Press), 2014. D. Vigneault Beery Helpx.adobe.com (19 April 2018). Asst. Professor, Technical Writing & Editing https://helpx.adobe.com/in/support.html. Metropolitan State University of Denver Hoffman, Ari. “The Evolution of Tech Comm: Journalism & Technical Communication Directing the Content Experience.” Intercom Campus Box 35, P.O. Box 173362 64.1 (January/February 2018) 6-8. Denver, CO 80217 LeVoir, Jake. “What Does the Average Video Cost?” 303.615.0181 SlateandMain.com (18 April 2018). http://www.slateandmain.com/blog/what-does- Stacy Barton the-average-video-cost. Asst. Professor, Video Production Lynda.com (19 April 2018). https://www.lynda.com/. Metropolitan State University of Denver Nakano, Chelsi. “The Four Different Types of Journalism & Technical Communication Learners, And What They Mean to Your Campus Box 35, P.O. Box 173362 Presentations [INFOGRAPHIC].” Prezi Blog (29 Denver, CO 80217 April 2016). https://blog.prezi.com/the-four- 303.615.0118 different-types-of-learners-and-what-they-mean- to-your-presentations-infographic/. Author Biography Shop.Canon.com (19 April 2018). https://shop.usa.canon.com/shop/en/catalog/ D. Vigneault Beery is the Assistant Professor for ca meras/eos-cameras. Technical Writing at the Metropolitan State Univer- Warren, Linda. “Are Learning Differences between sity of Denver in Denver, CO. Having earned a Mas- Generations A Myth?” MicroAssist.com (27 ters in Communication: Film Production & Aesthet- June 2012) ics and worked in Hollywood in various production https://www.microassist.com/learning- management roles for more than 6 years, while also dispatch/arelearning-differences-between- maintaining a production company for outside cli- generations-a-myth/. ents and documentaries, Asst. Professor Beery has continued to work at the very seam of these two in- YouTube.com (18 April 2018). dustries for over 20 years. https://www.youtube.com/. Stacy Barton is an Assistant Professor of Video Pro- duction at Metropolitan State University of Denver in References Colorado. Former film festival director, award-win- Advanogy.com. “Overview of Learning Styles”. ning scriptwriter, feature and short film producer and learning-styles-online.com (2004). director, Barton has worked in various genres & https://www.learning-styles- screened in film festivals and on TV, at home and online.com/overview/. abroad. In teaching, fiction scriptwriting, fundamental hands-on video basics, and crew-based produc- Bazilian, Emma. “Infographic: How Gens X, Y and Z tion process are her passions. Consume Video Content.” Adweek (February

Won't You Please, Please Help Me Find a Path to Leadership? Alisa Bonsignore

You don’t need to be the CEO to be a leader. The traditional management track may not be ideal for all personality types. We’ll discuss a variety of ways in which technical communications professionals can take the next step in their careers, even if traditional management roles aren’t available or desired.

Do you think of yourself as a leader? In truth, many decades ago, leaving a high-profile communications people don’t. That’s because they often imagine role to establish a company that places communica- leaders to be either extroverted ladder-climbers, or tions consultants with companies in Silicon Valley somehow ordained for their special roles. Many of and beyond. the leaders that you see before you at this confer- She not only mentors young communications pro- ence came to their roles in what you would probably fessionals, but has established a formal mentoring think of as non-traditional ways. program through Connext. The program not only Management isn’t for everyone. Let’s look at some helps those starting out, but offers experienced alternative ways to assume a leadership role with- communicators a chance to give back and share out taking on a staff. their valuable knowledge.

Project Management Teaching Many communicators find themselves thrown into a Rene is an excellent case study in how opportuni- project management role. Jessie Mallory, one of my ties dovetail. As part of her mentoring program at colleagues on the Board of Directors, says that her Connext, she has strong contacts with the commu- evolution into project management came unexpect- nications department at San Jose State University. edly. “I was hired by my current company to work on Over the years, she’s had many opportunities to a developer portal as a technical writer…. My boss speak to these students and recent grads. When of- didn’t give us a roadmap, just a goal and a three- fered the opportunity to teach, she jumped at it. week deadline to get the project up and running. We She’s described teaching as being very differently ended up self-organizing and breaking out the work fulfilling than her CEO role. “Teaching gave my into small tasks with daily planning meetings (a little business leadership a whole new perspective,” she like Scrum).” About a year later, her company for- says. mally asked her to serve as a project manager for their new cybersecurity venture. “Project management was a great next step for my Volunteering career, given what I enjoy (planning and working Volunteering can take place at both the local and closely with people) and my life goals. My founda- global level. For Lloyd Thompson-Taylor, it was a tion in technical writing has proven invaluable given gateway to new professional and personal opportu- the amount of communication and investigation that nities. I do on a daily basis.” Lloyd joined STC in 2015 and became involved as a student volunteer at the 2016 Summit. “It allowed Mentoring me to interact with speakers, STC leadership, and vendors, without any pressure (I’m a lifelong intro- Rene Siegel, CEO of Connext, has long been an vert) and let people learn my name.” Several STC entrepreneur. She founded her business two

29 Alisa Bonsignore

leaders have reached out to Lloyd, and he’s shared Author Contact Information his insights as a track reviewer for Summit proposals. He says that volunteering within STC has Alisa Bonsignore changed his career trajectory, and his higher profile Strategic Communications has helped him to land freelance work. Clarifying Complex Ideas https://ClarifyingComplexIdeas.com/ https://www.linkedin.com/in/alisabonsignore/ Thought Leadership 408.256.0621 Larry Kunz is a good example of using a blog for thought leadership. He regularly writes about tech- Author Biography nical communication on his blog, and actively partic- ipates in communications discussions on Twitter Alisa Bonsignore runs Clarifying Complex Ideas, a and other forms of social media. strategic communications consultancy that serves organizations around the globe. Her professional These are methods that should be comfortable for mission is to create clarity and build engagement, most communicators. Unlike face-to-face interac- giving people the information they need, when they tions from volunteering, speaking, or mentoring, us- need it. ing blogs and social media are an excellent way to put your communications skills to use in new and Alisa helps companies communicate complicated different ways. topics, including policy development and sustaina- bility communications surrounding the U.N. Sustain- able Development Goals (SDG); medical devices Speaking and pharmaceuticals/genomics; network security; and healthcare IT. She has been elected to a sec- If you’re comfortable, take your thought leadership ond term on the STC Board of Directors, and is to the next level as a speaker. The STC Summit chair of the STC Audit Committee. Prior to her and other regional STC conferences are always board service, she spent several years chairing ed- looking for new ideas and fresh faces for confer- ucational committees for STC and AMWA, and ence topics. People tell me, “Oh, I wouldn’t know working on conference committees for STC, IABC, what to say!” And then they proceed to spend 15 and the PRSA Health Academy. minutes speaking eloquently about professional development, or content strategy, or group dynamics In recent years, Alisa has been an active speaker at in a distributed working environment. You have national and regional events for STC, AMWA, the great ideas; don’t keep them to yourself. LavaCon Content Strategy Conference, and the Creative Freelancer Conference. These talks showcase her passion for professional development, a There’s More Than One Way theme that echoed in her contribution to the “Per- The big secret? There’s no right (or wrong!) way to sonality, Temperament, and Technical Communica- be a leader. The right way is the one that feels com- tion” issue of Intercom. fortable for you, builds your confidence, and allows Alisa lives in the Bay Area with her husband and you to find your voice. And when you find that son. voice—your unique, confident voice—it will open doors that you might not even know are there. I’m looking forward to hearing which methods work for you.

Case Study: Grab the Wheel and Drive Your Content to DITA Susanna Carlisi, Tom Aldous, and Adobe

Is DITA authoring a realistic choice when customers expect a wider variety of content in multiple formats, but you are faced with a limited budget and no tools team? This case study describes how a telecommunications company successfully implemented DITA authoring using a phased approach, with minimal dedicated staff, while leveraging its current toolset.

Drivers for Change Requirements for a New Authoring When we collected information from our customer Workflow base for our current documentation offering, it was To address the customer feedback, the following re- clear that we needed to improve the experience for quirements were created for a new authoring work- technical documentation users, to accelerate turna- flow: round times for customized publications, and to leverage existing content and toolsets. • Transition to structured topic-based authoring based on the DITA standard. Specifically, the following feedback led to the reevaluation of the documentation team’s format- • Adhere to a modest budget and limited re- ting-template based unstructured workflow. sources by completing the transition in phases. • Customers could not find required infor- • Adopt a tool that would allow us to convert mation because it is laid out differently current active content, while allowing us to across publications and it is not presented update and maintain unstructured docu- consistently across multiple products. ments that were in the queue for conver- • Customers didn’t know which publications to sion. use to from the multi-book product documentation sets to accomplish specific tasks. Structured Topic-Based Authoring • Some customers want large libraries of content detailing every product feature. Structured authoring is a guided workflow that en- • Some customers want the content narrowed forces consistent organization of information in doc- down to the feature licenses they pur- uments. Structure extends the role of the template chased. beyond a basic source of formatting for unstructured authoring, and instead turns the template into a • Some customers prefer succinct customized framework that exists behind each document. In documents that focus on quick start activi- structured authoring, because the content conforms ties or address a specific task or problem. to rules automatically, the documentation itself be- To create documentation that meets the needs of comes consistent. When documentation across increasingly diverse audiences and their web, mo- products is consistent, customers know where to bile, desktop, and print preferences, we decided to look for information because the content is predicta- refresh our authoring workflow. ble. Without topic-based authoring, there wasn’t a way to efficiently customize content according to customer preferences without excessive copy-paste operations and reformatting. The goal of modular, topic-based authoring is to create a large pool of

31 Susanna Carlisi, Tom Aldous, and Adobe

topics consisting of short and tightly focused con- The transition to DITA can be accomplished in three tent, to allow authors to draw on different subsets of phases: conversion, DITA element addition, and re- these modular topics to create diverse published use. Phase one starts with converting existing docu- materials. ments from unstructured to structured DITA content. Phase two includes adding strategic DITA elements Furthermore, by distinctly separating task, reference to content, such as the short description and and concept information into topics, structured au- metadata. During the third phase, we plan to focus thoring allows us to present these three categories on content reuse, which includes deploying a com- of information in a consistent way across product li- ponent content management system (CCMS) that braries, which contributes to content predictability, will allow us to fully benefit from the efficiencies of making it easier to navigate and to drill-down to rel- reuse. evant content. The goal of the conversion phase was to create an Phased Approach accurate reproduction of the content in valid DITA. That is, to create individual topics of the right type, A phased or staged approach to transition to DITA assembled in the correct hierarchy, into a DITA authoring is a realistic choice for small teams con- map. The result of this initial conversion was considering the leap to DITA with a modest budget. tent that could be published immediately. This approach allowed us to learn and implement After initial conversion, we added objects that we the DITA standard in bite-size pieces. When the did not have access to in the unstructured world, conversion process was finalized, conversions took such as the short description. At this point, no struc- place while one dedicated resource researched re- tural changes were made to the content. use possibilities and planned the metadata strategy.

Figure 1. Sharing and reusing topics in new contexts

32 2018 STC Technical Communication Summit Proceedings Case Study: Grab the Wheel and Drive Your Content to DITA

Only after completing the full conversion phase, was when processing our files for different uses the content scrutinized to remove reference and and types of output. conceptual information from procedures and to ensure that the content conformed to the principles of minimalism. The advantage of this approach is that Planning a Successful Conversion each individual documentation product team can The FrameMaker structured application and conver- decide on the schedule for restructuring product sion tools consist of the following components: content, while the entire documentation team is making the move to DITA. The refining of the con- • Document Type Declaration (DTD): In tent was left up to the individual teams. markup, a set of declarations determining such things as the markup to allow in a doc- The conversion phase was completed with one full- ument and the elements and attributes for a time equivalent and a consultant. document set. • Element Definitions Document (EDD): A Toolset FrameMaker document that contains a set of element definitions for a class of docu- Our team decided to remain with Adobe Frame- ments. The EDD includes rules for applying Maker to author DITA content. With Adobe Frame- formatting according to context. Maker 2017, the same toolset can be used to author DITA content and maintain unstructured content • Extensible Stylesheet Language Transfor- that is in the queue for transition. Furthermore, the mations (XSLT): A language for transform- 2017 release of Adobe FrameMaker enabled us to ing one XML document into another XML implement topic-based DITA authoring and transi- document. XSLT stylesheets are useful for tion to XML publishing without requiring an expen- pre-processing or post-processing DITA sive custom XML infrastructure. FrameMaker was content. used to transition from unstructured to structured • Template: A FrameMaker document used to content without disrupting business continuity. create new documents. The template includes all the formats and structure descrip- Structured FrameMaker is a natural fit for DITA for tions. The EDD is imported into the tem- the following reasons: plate. • It supports standard DITA structures out of • Read/Write Rules: In FrameMaker, inter- the box. preted commands you supply to modify how • It includes many advanced tools to help cus- the software translates between Frame- tomize DITA templates to our needs. Maker and markup documents. • The process for publishing DITA content is • Conversion table: In FrameMaker, a table similar to other publishing processes we’re associating parts of an unstructured docu- used to (using FrameMaker to generate ment with their structured counterparts, PDFs, for example) and does not require used in converting an unstructured docu- building a costly publishing solution. ment to a structured document. • It can publish the same content in different We engaged a contractor to customize the Frame- formats, such as HTML and EPUB. Maker structured application and the conversion • If you already use unstructured Frame- tools. Maker, transitioning to Structured Frame- Depending on your content, conversion can be the Maker builds on an existing investment. most complex phase of transitioning to DITA, partic- • The familiarity of the FrameMaker environ- ularly if your content does not align one-to-one to ment makes the leap to XML and DITA pub- DITA elements. lishing easier. Because of the large volume of content we needed • The Structured FrameMaker interface is to transition, we opted to build a conversion work- very good at guiding (and requiring) authors flow that automated most of the manual and repeti- to create content that conforms to our un- tive tasks in an effort to reduce impact on the au- derlying template. This is enormously im- thor’s time. portant for preventing issues that can arise

2018 STC Technical Communication Summit Proceedings 33 Susanna Carlisi, Tom Aldous, and Adobe

Existing content rarely translates directly to the • Addressing legacy content that inherently in- DITA standard; however, creative solutions built cludes overrides, formatting tags, cross-ref- with XSLT, read-write rules, and scripts can effec- erence issues, and other difficult-to-find tively prepare the content for the conversion. remnants. The conversion solution addressed the following • Automating the process as much as possi- key challenges: ble to avoid disruption. • Delivering a user-friendly publishing solution • Categorizing unstructured topics as DITA that allows the import of variables and con- concept, reference, or task upon conver- ditions. sion. • Converting content despite minimum restructuring before conversion (such as un- Categorizing Topics Prior to Conversion tangling conceptual information from proce- To categorize unstructured content to DITA topics of dures). the correct type, we applied unique paragraph tags • Retaining some unstructured FrameMaker to the headings of the unstructured sections to des- objects, such as conditional text and varia- ignate them as a reference topic or a concept topic bles, in the early phases to support a (for example, r_h1 for a reference and c_h1 for a phased transition. concept). The remaining sections were automatically categorized as tasks. Since the bulk of our content is procedures, this method reduced the amount of tagging the authors had to complete.

Figure 2. FrameMaker tools for a successful conversion

34 2018 STC Technical Communication Summit Proceedings Case Study: Grab the Wheel and Drive Your Content to DITA

Figure 3. Conversion table sample We then set up the conversion table to structure retained. To address this, we created an Extend- every topic as the strictest topic type: the task. Once Script that would search for incorrectly applied char- the document was structured, we ran an XSLT acter formats and capture these formats in the con- stylesheet to read the tagged headings to correctly version table. The conversion table then defined categorize the topics as concept, reference, or task. how to properly wrap the content in the correct DITA elements. Minimizing Content Rework Before Con- Legacy content also included many formatting-spe- version cific tags that do not have an equivalent in DITA, for example, end of procedure tags. We needed to de- Some of our content, particularly procedures, in- lete these formatting tags, which is a time-consum- cludes multiple information types in the unstructured ing manual process. To address this issue, we cre- environment. Specifically, procedures often contain ated an ExtendScript to search for and delete for- conceptual and reference information. To address matting paragraph tags. this challenge, we converted each procedure to a series of nested tasks to retain subtitles in the over- Cross-reference issues must also be considered. all task. Problems with cross-references in our content stemmed from these two issues: This approach lets each documentation product team define the schedules for “untangling” content, • Multiple paragraphs with the same cross- such as removing the conceptual and reference in- reference marker. This occurs because new formation from procedures. chapters were created from existing chapters (duplicating the cross-reference maker). Retaining Some Unstructured Frame- • Paragraphs included more than one cross- reference marker. This occurs because in- Maker Objects dex markers are often mistakenly inserted Since our approach is a phased one, we needed to as cross-reference markers. retain variables and conditional text in the early To address these cross-reference issues, we cre- phases. Variables were wrapped in the DITA ph el- ated an ExtendScript to add the chapter names as ement and designed to use the FrameMaker Varia- the prefix to every cross-reference marker. Doing so bles dialog, as in unstructured FrameMaker. The ensures that the cross-reference markers are publishing solution uses an ExtendScript to import unique. We also created a second script to check variables and conditions across a publication. for and fix paragraphs that included multiple cross- reference markers. Addressing Legacy-Content Issues Legacy content often contains issues created by applied format overrides. However, some of the format overrides, though incorrectly applied, needed to be

2018 STC Technical Communication Summit Proceedings 35 Susanna Carlisi, Tom Aldous, and Adobe

Automating the Conversion Process https://help.adobe.com/en_US/FrameMaker/12. 0/StructuredDev/Structure_Dev_Guide.pdf. We created a user-friendly conversion workflow by: Adobe Systems Incorporated. Using Adobe • Allowing authors to run scripts from a cus- FrameMaker (2017 Release), 2018. tom menu in FrameMaker https://help.adobe.com/en_US/framemaker/201 • Using different structured applications for 7/using/framemaker_help.pdf. conversion and authoring Aldous, Tom. “Publishing DITA with FM 2015.” • Using Read/Write rules to roundtrip XML Adobe. (11 March 2016). • Using stylesheets to adjust structure where https://blogs.adobe.com/techcomm/2016/02/we necessary binar-framemaker-dita-tom-aldous.html.

Leveraging FrameMaker Publishing Author Contact Information Our publishing solution leverages and extends out- Susanna Carlisi of-box FrameMaker publishing. To define publishing Content Strategist & Tools Specialist parameters, we edited the default FrameMaker file Ciena provided to configure the generation of the output 2351 boul. Alfred-Nobel, from a DITA map: ditafm-output.ini. We chose to in- Saint-Laurent, Qc H4S 2A9 clude an intermediate step of publishing the DITA 514.228.5495 map to a FrameMaker book so that we could run a script to import variables and conditional text set- Tom Aldous tings from a predefined “control” file into the result- Founder/CEO ing book file. We then used the book to publish to The Content Era PDF, EPUB, or HTML output, directly from Frame- 8601 Marlei Ln. Maker. Arcadia, FL 34269 508.617.7763 Conclusion Author Biography By transitioning in phases, it is possible for smaller teams that do not have access to an expensive Susanna Carlisi is a Content Strategist & Tools XML infrastructure and associated tools to imple- Specialist at Ciena. Serving as a technical commu- ment a DITA authoring environment. nicator and tools manager for most of her 18 years at Ciena, she has an in-depth view of end-user doc- As this case study shows, we successfully con- umentation requirements and writer processes. Su- verted our content to DITA within our modest sanna manages and supports all tasks related to budget by creatively manipulating our source con- authoring tools setup and maintenance, authoring tent, leveraging our existing tools, and relying on a standards, and publication/single-sourcing pro- single contractor for scripting and overall direction. cesses. Susanna has been a key player and valuable asset during the transition Ciena has made to a DITA XML environment. Resources Tom Aldous is the Founder and CEO of The Con- Adobe Systems Incorporated. Adobe FrameMaker tent Era. For many years, Tom has been well known 12 Structured Application Developer Reference, throughout the Technical Communications Commu- 2014. nity as an expert in XML, structured authoring, and https://help.adobe.com/en_US/FrameMaker/12. content strategy. In addition to his technical skills, 0/StructuredDev/Structure_Dev_Reference.pdf. Tom is an expert at reading into the bigger business objectives of an organization and crafting a solution Adobe Systems Incorporated. Adobe FrameMaker that fits their content requirements, increases pro- INI Reference, 2017. cess efficiency, and improves their bottom line. Tom https://help.adobe.com/en_US/framemaker/201 has successfully applied similar methodology that 7/ini/framemaker_2017_ini_reference.pdf. went into the Ciena DITA transition for many other Adobe Systems Incorporated. Developing customers, and provided the guidance that Ciena Structured Applications with Adobe needed to make the transition a reality. FrameMaker 12, 2014.

Your Mind is the Most Valuable CMS: Deeper Working Independent of Technology Kim Chmielewicz

Technical communicators in environments that do not invest in the latest tools and applications may feel disadvantaged by a perceived lack of resources. In such scenarios, writers/illustra- tors/information architects do not need to do more work, but deeper work.

This workshop will give you some ideas and tools to maximize your communication skills in any scenario.

What is deep work? Consider how children now take buses to school: 1. They wait in their driveways (if not inside “Deep work” is significant reflection and thoughtful their houses). organization that does not center on displaying information in automated formats but customizes 2. They take a bus (with their own individual communication structures to reflect the way data is stops). actually used. 3. The bus picks them up (adults oversee the entire process). Why do I need to learn about Rather than segmenting work tasks, create a cohe- sive narrative. deep work? The most difficult aspects are taking the time to lis- Consider the following statements and if you agree ten and plan your project. or disagree: However, you can still reuse content as agility can • Communication is used more often than reference your ability to organize information quickly ever. [Probably a firm yes] once an approach is conceived. • Communication engages more people than ever. [Yes, with some exceptions Five aspects of deep work • Communication expectations are higher than ever. [Yes and no, dependent on per- 1. What we know spective] 2. What we think 3. What we understand How can deep work help me to 4. What we experience communicate better? 5. What we project Picture communication practices as analogous to raising children. Knowing—What are the facts influencing this work? Consider how children used to take buses to school: Reflecting back on the school bus example, try not 1. You walked to the stop (alone). to be overly influenced by perception, but by what is 2. You waited at a stop (with other kids). actually present now or true. 3. The bus picked you up (adults assumed this was a given).

37 Kim Chmielewicz

Thinking—What is the source of those facts? Solicit collaboration throughout deep work to un- Author Contact Information cover more directed resources. To encourage open discussion, use a progress log to foster efficiency Kim Chmielewicz when integrating contributions. Technical Communicator East Amherst, NY [email protected] Understanding—What analysis is applied? www.linkedin.com/in/kim-chmielewicz Think like an anthropologist and also consider pur- 716.207.5260 pose and meaning. Who should be most readily served by the ultimate solution and their perspec- Author Biography tives must be examined. Kim Chmielewicz holds degrees from Hamilton Col- lege in Clinton, NY, and the University of Buffalo Experiencing—What are employees/customers School of Medicine and Biomedical Sciences in an- dealing with? thropology, creative writing, and clinical laboratory Also integrate and consider what we think is achiev- science and is in the process of completing an MBA able based on our past experiences. at Rochester Institute of Technology. As well, take into account what are the available re- Kim has worked as a staff and contributing writer at sources to be utilized, and variables to be used, in- both domestic and Irish newspapers with stints in cluding a mind map of the most important aspects. marketing and public relations that included the design, creation, and production of promotional litera- Projecting—What is the ideal result of deeply work- ture; as a trainer and tutor; and as a technical and ing? proposal writer in various professional environments including non-profit agencies, educational institu- Instead of starting at the beginning, approach stake- tions, research laboratories, public health education holders and ask them to muse about what they and data collection, IT application and database de- want: project the result and work backwards. velopment, engineering and manufacturing, banking Methods used to solicit feedback may include devel- and finance, and aerospace/defense contractors for oping a basic plan template, perhaps as a flow both private industry and the US government. chart, and discussing it with your collaborators. Kim is a member of the STC Rochester chapter and Also consider how to generate buy-in when a solu- has presented at several STC Rochester Spectrum tion begins to emerge, including revisions/future conferences on other topics related to writing more support. effectively and promoting the need for and value of technical communication across all employment sectors. Takeaways 1. Working deeper within yourself 2. Working deeper without (with others) 3. Synthesizing the two categories of deep work for best results Anyone will be able to utilize professional experiences and unique best practices with considered analysis to honestly reflection on solutions. Practice techniques that enable closer listening to your occupational muse and your collaborators in service of asking better questions to obtain more robust insights. This discipline leads directly to more useful and valuable outcomes for your customers and extends your confidence in your communication skills.

Policies and Procedures—Communicate the Future Dawnell Claessen, Emily Kowal, and Ann Marie Queeney

A presentation and discussion about the future of the profession of Policies and Procedures and our roles and the nature of our work in that future. This session will present attendees with ideas about the skills that will be most valuable for Policy Analysts, Procedures Writers, Compliance and the Process Specialists of the future. We will discuss the technologies and methods that will allow us to continue to contribute to process improvements and to the success of our organizations. This session will also discuss what will likely remain the same, and skills that are important now that we can carry into the future in our field, followed by what is sure to be different and new for Policies and Procedures Practitioners’ work in the future. This session will be beneficial to any attendees engaged in or interested in Compliance, Process Improvement, Policies and Procedures, Quality Processes and Regulatory Affairs.

practice for Technical Communicators and P&P Session Info Practitioners. Key Takeaway: The basics of writing and editing Learning Objectives will still matter in the future. Analysis and To inform attendees on what the field of Policies Research skills will become more important in and Procedures Communication may look like in the future. the future and how we can begin to develop the Emily will talk about the Future of How We Will skills of the future. Work, delivering remarks about the techniques and tools and technologies that we see Learning Activities emerging and enabling our work in the future. She will address how this could work for Each of the three speakers will present about governance and legal compliance and identify 10-2 minutes of prepared remarks on the some of the unique challenges of How We Will general areas described below. This will be Work in the future. followed by discussion among the group and Key Takeaway: Subject Matter expertise will questions and answers. To make sure the Q & remain important, but being flexible and willing A session gets going, each presenter will to adapt and adopt new technologies will prepare one or two questions in advance. A become more important. moderator will be appointed to facilitate the discussion and keep the question and answer Ann Marie will deliver remarks on Where We session moving along. Will Work, discussing how our skill set will be staffed across numerous industries and the Dawnell will present a short overview of future niches within the field and within organizations and current skill sets for P&P practitioners and large and small. Ann Marie will describe how a highlight those skills that we need to develop documentation project in the medical device and grow for the future. This will address the industry led her to a career that has included “Future of You” at work. Dawnell will also talk regulatory affairs, compliance and policies and about her recent work with Risk Communication procedures analysis. and identify new opportunities and new areas of

39 Dawnell Claessen, Emily Kowal, and Ann Marie Queeney

Key Takeaway: Where (geographically) we work will become less important in the future, but which “areas” of practice we are in will matter Author Biographies much more in the future. Dawnell Claessen is a senior policy analyst Potential questions / topics of discussion: specializing in risk management and security compliance for the United States Department of • The recent example of a dress code Defense. Dawnell holds a Master’s degree from policy that a large corporation crowd- the University of Texas at Austin in Library and sourced by means of its entire body of Information Science with a focus of study on stakeholders—employees, customers Federal Information Policy. and suppliers. Emily Kowal is a Policy Manager for Walgreens • How might “know your audience” where she manages a global team of policy and change in the future—if everyone is your procedures specialists and compliance analysts potential audience? and was recently involvement in implementing • How will we know who/where our SMEs an enterprise-wide governance program. Emily are? holds a Master’s degree in Rhetoric and Professional Writing from Northern Illinois Handouts University. An annotated outline will be developed and Ann Marie Queeney of A.M. Queeney, LLC presented to highlight the prepared remarks of specializes in procedures for the healthcare each speaker. The presentation, along with industry. She has over 18 years of document information resources and contact information specialist experience in the medical device for the speakers, will be handed out to the industry. Her services include technical writing, attendees as well as made available on the editing, compliance assessment, and skills Summit website and SlideShare. On their first training. Ann Marie, a senior STC member, is day back at work, attendees will be able to see co-manager of the Policies & Procedure SIG a summary list of the skills (new and old), and past co-manager of the Technical Editing technologies, and industries that will be SIG. important to the Policies and Procedures Practitioners of the future.

Moving Content through the Workflow: Frustrations and Fixes Erica Cummings

“Did you get a chance to review that draft I sent you?” As writers, it’s a question we’ve all asked. And at some point, most of us have gotten little more than a blank stare in response. Perhaps one of the most frustrating aspects of writing is getting the type of feedback you need, in the format you need it, in a timely fashion. The more steps in the writing/editing workflow process there are, the higher the chances it can get hung up somewhere. But we can’t just ax the process altogether. We need feedback to ensure we deliver quality content.

In this article, I discuss some of the frustrations we all experience when attempting to move our content through the workflow process. More importantly, I’ll cover some of the solutions I’ve seen work at my own company.

writing/editing. It’s one of the ways we ensure a Frustrations quality deliverable. But it also makes for quite the I work in the fast-paced industry of cybersecurity time crunch when multiple people need to review consulting. This industry requires managing multiple lengthy and technical content, and deliver to the cli- projects at a time and meeting tight deadlines, all ent, all within a week’s time. while ensuring a quality deliverable that meets client We haven’t always been great at managing this pro- expectations and provides actionable information. cess. But over time, we’ve become pretty efficient. But I’m preaching to the choir. Technical communi- How? It’s all about getting people, process, and cators are all too familiar with this situation. technology in sync. While trying to meet these expectations, technical communicators often run into a roadblock: moving People content through the workflow. People define the culture at an organization. A cul- We can pour our heart and soul into our work and ture that emphasizes accountability, teamwork, and craft an amazing piece of content, but if we can’t get excellence is the basis for producing any high qual- the appropriate individuals to review our work in a ity service or product. timely manner, the whole process can grind to a halt. And we get it—people get busy, they get distracted, they “forget.” But when our work relies so How We Do It: Matrix much on feedback and input from others, we need In order to cultivate these values, our company lev- to find a way to keep the process going. In the fast- erages a matrix organizational structure. With the paced future of technical communication, maintain- way we have implemented the matrix, we have tra- ing an effective process for moving content through ditional/departmental managers, but we are also ac- the workflow is essential. countable to people in multiple business units on a per project basis. In this model, if a deliverable gets My Experience held up during the project, we are all responsible to one another, and of course, the client. Our team of technical communicators works hand in hand with subject matter experts, business consult- Generally speaking, leveraging the matrix in this ants, and quality assurance to produce deliverables way results in: for our clients. Each deliverable our team creates • Less red tape—you are empowered to do goes through multiple rounds of review and revision. what you need to do to get the job done. At minimum, there are five people involved in

41 Erica Cummings

• More personal accountability—since you sources to accomplish a task. With respect to con- have to please (and get results from) people tent workflows, the importance of establishing a not directly in your department, you have no consistent, repeatable process cannot be over- choice but to perform well and to work as a stated. team. • Increased flexibility—project teams are not How We Do It set in stone based on functional lines of business, so team members can be custom- Using our process as an example, we’ve defined ized based on skillset and interest. the following roles and responsibilities for individuals directly involved in creation/review of a deliverable. How You Can Do It • Consultant—performs assessment, is more Roles and Responsibilities: Matrix or not, clearly technically focused establishing roles and responsibilities is the founda- • Technical Writer (TW)—receives raw data tion to an effective workflow. Define who should re- from research analyst, writes draft of deliv- view what and on what timeline. Communicating erable, manages edits to deliverable (and formally documenting) this information will help throughout the process to create the culture of accountability that facilitates quality content creation. • Project Owner (PO)—oversees strategic direction of project, reviews deliverable to en- Consistency: Though client deadlines may vary sure it aligns with overall client goals from one project to the next, the expectation of ex- • Subject Matter Expert (SME)—not involved cellence and accountability team members have for in initial work in the project but reviews de- one another should remain the same. If certain roles liverable for technical accuracy are expected to review content within 24 hours, this should be enforced all the time, regardless of • Quality Assurance (QA)—provides final re- whether the client actually needs it on such a tight view (sanity check, editing, grammar, for- schedule. In this way, consistency is what enforces matting, adherence to internal style guide) excellence, and the process becomes second na- Though not directly involved in the writing/editing ture. process, there are also a Project Manager and a Getting buy-in: For those organizations who strug- Scheduler who handle logistics and budget of the gle with shifting culture in this direction, you may be project, including scheduling deliverable review able to get buy-in by emphasizing the tangible ben- times and managing due dates. efits. More efficient workflows result in happier cli- The workflow for the deliverable is as follows: ents, which of course leads to greater revenue and a better reputation in the industry. It also frees up • Assessment is performed your internal resources to move on to other projects • A knowledge transfer meeting is held with so that their utilization increases. Since projects are Consultant, PO, and TW to discuss findings completed in a more timely fashion, there’s less and shape recommendations for report. chance for multiple, halfway complete projects to • TW creates report shell and drafts the re- build up, which leads to increased stress levels. port. Given the velocity of this process, consultants can • Consultant reviews/edits draft focus on a smaller number of projects at a time, which ultimately leads to greater quality of work. • PO reviews draft • SME reviews draft • TW/Consultant address comments from Process PO/SME review Process provides the structure for getting a job • QA finalizes report done. Having a mature process in place helps rein- • Project Manager delivers report to client force the culture and optimize technological re

42 2018 STC Technical Communication Summit Proceedings Moving Content through the Workflow: Frustrations and Fixes

Figure 1. Project workflow • Pulls in client specific data. How You Can Do It • Maintains a single source of QA’d content. Document: It may sound mundane, but documenta- • Integrates with SharePoint, which provides: tion helps to reinforce expectations. Most of the • Shared editing capabilities content technical writers produce undergoes multi- • Version history ple revisions. Without clearly defined expectations, deadlines, and procedures, the process would un- • Filterable and searchable database of ravel. Whatever the process is, document it! past and current docs • Tracks workflow, due dates, etc. so that all Delegate: Rather than relying on one individual to team members have insight into the work- perform all functions of the project (scheduling, per- flow status. forming the assessment, writing the report, managing reviews, delivering the report), consider delegat- This tool has provided immense benefits for us, in- ing responsibilities for the workflow to people who cluding: enjoy/excel at different aspects of the project. Not • Automation: everyone is great at time management, so leveraging project managers or schedulers can help keep • Builds the shell for a document easily workflows on track. Not everyone is great at writing, and quickly. so leveraging writers who both construct the deliver- • No need to copy / paste from previous able and have the most insight into the current reports and risk cross contamination of workflow status can lead to quality, on-time deliver- client details. ables. Again, establishing roles and responsibilities • Automates workflow emails so that is key to making this model work. Beware that dele- members of the team receive an email gation can lead to compartmentalization, where indi- when the content is ready for their re- viduals may avoid taking ownership for a task that is view. not explicitly designated to their role. It’s important • Consistency: Offers consistency in lan- to emphasize that while different aspects of the pro- guage, formatting, etc., while still allowing ject are delegated to different people, everyone is documents to be tailored to client’s needs accountable for making sure the deliverable meets after they are assembled quality standards and client expectations. • Repeatability: Anyone creating a document pulls from the same collection of stock verbi- Technology age and formatting. • Efficiency: Technology is great, but it’s important to note that technology alone will not solve deeper issues of cul- • Expedites the content creation process ture or process. That being said, technology can be by providing stock verbiage you can de- used to support or help implement a process for fine ahead of time. more efficient workflows. • Tracks content workflow and due dates. • Quality control: How We Do It • Tracks version history, so no need to save locally and upload multiple ver- We use an automated document assembly program sions of a document with incongruous (which interfaces Word with SharePoint) that does edits. the following: • Tracks who made edits and when. • Provides template + stock language as a • Doesn’t rely on users having magical starting point for document creation. formatting powers to create a decent • Allows for easy branding/style changes. looking document.

2018 STC Technical Communication Summit Proceedings 43 Erica Cummings

Figure 2. Document creation

• Branding: Enforces consistent colors, fonts, styles across all documents by defining Author Contact Information them in the base template. Erica Cummings Technical Writer How You Can Do It RSM US LLP Centralize: Depending on the size of your organiza- 23340 N Miles Rd tion and available resources, you may not be able to Bedford Heights, OH 44128 invest in a centralized document management sys- 216.927.8200 tem. Still, centralize what you can. Assign a specific file storage system to try to limit the number of local, Author Biography incongruent copies floating around out there. In a previous life, I was an adjunct English/Humani- Communicate: Even with automated workflow ties instructor. Literature was my first love, but I’ve alerts and fancy technology, communication can still found a new love in cybersecurity. Now, I'm a Tech- fail. Communicate what you need, when you need nical Writer working at SecureState, an information it, and which role is expected to respond. security consulting firm that was recently acquired This brings us back to our initial point: improving by the tax/audit/consulting firm RSM. In this role, I content workflows requires a combination of people, take technical security information and translate it process, and technology. One without the others is into easily digestible content. This includes technical incomplete. By emphasizing a culture of accounta- reports, executive summaries, blogs, white papers, bility, formalizing a process, and leveraging tools website content, case studies, and sales docu- where you can, you can find solutions for moving ments. content through the workflow. In my free time, I enjoy being outside, being active, spending time with my husband, reading, and root- ing for the Michigan Wolverines! References Stuckenbruck, Linn C. “The Matrix Organization.” Project Management Quarterly 10.3 (September 1979): 21-33. https://www.pmi.org/learning/library/matrix- organization-structure-reason-evolution-1837.

Using Regular Expressions with Madcap Flare: Putting Your Searches on Steroids Robert Delwood

Regular expressions take find and replace to new levels. You can find text patterns, not just exact text. With patterns you can find, replace and even format all phone numbers, replace all span tags in a Flare document (“my text” with "my text"), find every e-mail address in a document all documents names, all dates formats, and words you’re not even sure how they’re spelled, like Jeffrey, or Jeff, Jeffery, and Geoffrey. Do each of these in a single search.

This ability, using a notation called regex, is described as find on steroids. Learn how Madcap Flare supports find using regular expressions. It’s not limited to just Flare. This works with any text based product. With other tools, such as NotePad++, you can make changes to one or more files at the same time. It’s versatile enough that writers and programmers alike can use it, and opens a new world to find and replace.

Everyone is familiar with the Find feature. It’s a companies to include them. Except they may not be ubiquitous feature that almost every application has minor or uncommon for the writer. All much more built in, and that we’ve come to rely on frequently. the reason to fully utilize the ones we have. And Yet, for as simple and powerful the feature is, it regular expressions should be added to our list. seems few take full advantage of it. For instance, think about the times in the last month you’ve done a find within a document. Chances are it’s a com- What Are Regular Expressions? mon event. Now, think about the times in the last Regular expressions, also called regex, are a pat- two months you’ve done a find on two or more doc- tern-finding notation. It’s a find feature but instead of uments at the same time, a multiple document find. finding matches based on exact text, it can find pat- This number is likely dramatically less than the first. terns. For example, we’re all used to conventional And finally, in the last three months the number of finds when you enter the exact text, such as ubiqui- times you’ve done a find and replace on two or tous or idiomatic, and the find locates instances of more documents at the same time, a multiple docu- that text exactly in the document. There may be ment replace. Likely, that’s almost zero. So why the slight options variations such as upper and lower precipitous fall between each case? I’d like to talk case (Ubiquitous/ubiquitous), or whole word only, about that. This paper is about reviewing the lowly but those don’t change the point here. It’s still look- find feature and elevating it to a new, high status. ing for a letter to letter match. I’ve always maintained that writers are about being It’s pattern finding. Regex looks for patterns or a put upon group. We will never get the number of specific groupings based on wild cards. As an ex- tools we really need. Tools here are defined as ample, sometimes you want to find something but small applications or features within an application you don’t know what you’re looking for. Suppose the that help writers do their job. Those are the ones for document is full of serial numbers, defined as six the low level tasks, such as formatting text, listing numeric characters in a single string, such as files in a directory, and especially automating tasks. 456923. You don’t know what the serial number is These tasks may be onetime events, unique to each ahead of time, and perhaps you don’t even care. writing group, even idiomatic for individual writers. You just want to find them. That’s where wild cards It’s understandable then why we will never get those come in. A wild card is where a single character tools. They’re too minor or uncommon for

45 Robert Delwood

matches more than one character. In a conventional every Web site reference, cataloging it, and report- search, one character matches one character. For ing if the site is available or not. Regex is able to ubiquitous, u matches u, b matches b, and so on. find the pattern match, and the language provides With a wild card, one character matches multiple the repetition, logic, and automated support. characters. The regex notation \d matches any numeric digit, the characters 1 through 9 and 0. So instead of having to specify the exact number, such How to Use Regular Expression as a conventional find would do, you could enter Regex is a rich, versatile, and sometimes complex \d\d\d\d\d\d. The series of six numeric wild cards notation, so it’s not possible to cover every concept would match any six numeric characters. in this brief paper. Instead, I want to present funda- It’s a notation. Regex is considered a notation and mentals so that you can understand what’s possi- not a computer language. It doesn’t contain any ble, and then it’s just a matter of matching up terms built in logic, any predefined functions, and can’t to meet your needs. use language features such as If statements or There are five important concepts: Literals, wild- looping. It uses keyboard characters to define the cards, range, repetition, and position. matching sequence. That means it also shares some of the letters and symbols in common. In the Literals. Literals are the keyboard characters. numeric wild card case of \d, it uses the backslash These are the letters, numbers, and symbols that to differentiate this meaning from the conventional we’re used to with conventional searches. You can meaning of the letter d. use only literals for your regex searches. You’d lose the power of regex. This isn’t limited to the 96 char- However, regex does need to be run by something. acters on a keyboard, but also includes the possible It may be built into the application. Madcap Flare 1,114,112 Unicode characters. supports regex, as does the application NotePad++, an enhanced version of Windows’ venerable Note- Wildcards. Wildcards are single characters that can Pad. Word supports a wild card notation although match multiple characters. This is mentioned earlier it’s not generally considered as regex. All three sup- with the \d wildcard matching any numeric digit. Re- port both find and replace wild card features. Other gex has a rich set of wildcards. applications support just regex features, and may . Any character be needed for specialized or specific find issue. \s Any whitespace Regex is more of a guideline that an actual product or even a standard. Since applications have to sup- \S Any non-whitespace port and run regex, there is some variation from the \d Any digit regex ideal. That means each application’s version is slightly different and will use different names. \D Any non-digit Grep, PCRE (Perl Compatible Regular Expres- \w Any word character sions), and almost each language such as Microsoft .NET, UNIX, Java, and Python will have their own \W Any non-word character variations. The products are largely similar; perhaps The period, for example, is the most versatile wild- 80% are the same in each version. The differences card because it matches any single character. For will reflect the language’s concentration on different example, c.t would match the pattern c, any charac- material such a string or mathematical processing. ter, and t. This includes the obvious ones of cat, cut, Even though regex isn’t a language, it can be used and the time abbreviation cst, but it also can find by languages. Almost every language supports re- matches anywhere within a word such as citizens, gex and can be used to make regex calls. In fact, Scottish, and classification. the true power is regex is best seen in a language It’s useful to point out that any regex notation can where repetition and processing can automate the be made into a literal by using what is called an es- process. Imagine having a scientific instrument that cape character. This is a backslash (\) immediately can collect thousands of inputs per second. An ap- before the character. If you wanted to find the pe- plication can loop through that data, perhaps into riod at the end of a sentence, you couldn’t really use the billions, and find and catalog highly complex the period notation, since that’s a wild card and patterns. In a more practical example, imagine be- would not only find a literal period but also any other ing able to go through a long document, finding character. In this case you’d use \. to indicate

46 2018 STC Technical Communication Summit Proceedings Using Regular Expressions with Madcap Flare: Putting Your Searches on Steroids finding a literal period. The same is true for finding a Regex provides two ways to provide repetition: ex- backslash character, such as \\. plicit and implicit. However, often you’re not interested in finding just Explicit repetition notation uses the curly brackets. If any character, you want to find a specific character one number specified, then the pattern will be re- or a kind of character. We’ve already seen the digit peated exactly that number of times. So \d{6} as wild card of \d. The \D (with an uppercase D) finds mention matches exactly six digits. This means a any character other than a digit. \w finds any word digit string of five or less will not be matched at all, character. That is any letter (which includes key- and if the digit string is more than six, then only six board and Unicode) number, and underscore. \W is will be matched. That would be the first six digits un- any character that is not considered a word charac- less otherwise specified. If two numbers are inside ter. \s is any white space character. This is any the curly brackets, then the first number is the mini- space character and also tabs, line feed, carriage mum number needed to make a match, and the return, and new line characters. \S is any non-white second one is the maximum number that will be space character or any character not included in the matched. So \d{2,6} matches two to six digits in a white space category. row. If you’re looking for a user name, defined as six to 12 alphanumeric characters, you could use [a- Range. Hopefully the power of the regex is started zA-Z0-9]{6,12}. This would fully match Pvt- to be seen. Combining literals and wildcards adds a Dancer98, match the first 12 characters of Pri- versatility that a conventional find can’t match. For vateDancer98, and not match PvtDc at all. example, finding any serial number is an improvement over the conventional find. And you can com- Implicit repetition notation finds sequences based bine literals with wildcards to find more specific se- on zero, one, or more occurrences. The notation im- rial numbers, such as using 1/d/d/d/d/d to find all mediately preceding the following characters will at- serial numbers beginning with the number 1. Even tempt to be found. so, just those two are still limited. With the range no- ? Finds zero or one occurrences tation, you can set a range or a group of characters to find. This notation finds any character inside hard * Finds zero or more occurrences brackets, ([]). This can be any set of characters, ex- + Finds one or more occurrences plicitly listed like [AEIOU]. It can be a range, with the first and last characters noted like [a-z] or [1-0] For example,

r-z. (which has two uses and the second one is men- Repetition. This is the ability to repeat a sequence. tioned later) makes the proceeding character op- To find six digit serial numbers, we’ve been using tional. As examples, ou?r would find the English the \d\d\d\d\d\d notation sequence. An obvious and American spellings of the words colour/color, problem with that is there are six repeated values. and humour/humor. Sequences like that should almost always be Position. So far, most of the searches above will avoided. They’re hard to maintain, duplicate, and match the sequence anywhere in the word, whether change. Regex uses the curly brackets ({}) to indi- it’s the entire word itself or a limited sequence within cate the number of times the immediately preceding a word. For example, \d{6} matches 123456. It also notation should repeated. The serial number se- not only matches the first six digits in the seven digit quence can now be shortened to \d{6}. 1234567 (123456) but also the last six digits in the same word (234567). This is a case conventional

2018 STC Technical Communication Summit Proceedings 47 Robert Delwood

finds don’t often have to deal with. Most of those formatting may affect how the text displays, depend- have an option to find whole word matches, perhaps ing how span_1 is styled. Assuming that’s the case, on by default. Regex has two important position it needs to be cleaned up. There are two cases that finding characters: this is helpful in. ^ Start of word The first case is that the span_1 and span_2 is un- wanted and should be . It may have been The caret (^) will find matches that start at the be- introduced during a file import process. In that case, ginning of the word. This means ^\d{6} will only find we have the additional concern that there might be a match if it’s at the beginning of the word, the a span_3, span_4, and so on. Or it may have been 123456 from 1234567 and not the second instance, intentional at one point but now you want it 234567. The dollar sign ($) is the opposite and changed. In any case, we want to change all those matches only at the end of the word. \d{6}$ spans to span_Iago_reference. A simple find and matches the sequence at the end of the word, replace might work if we were sure there were only 234567 from 1234567, and not 123456. Using both a span_1 and span_2. We want to catch all the in- will find the match only if it’s at the beginning and stances include unexpected ones. Regex simplifies the end. That is, if it’s the entire word. ^\d{6}$ this. You can find matches only the word 123456, and will not match and replace with . The find matches the literal part of . Again, regex can do that. It takes make an assumption that that is well formed and two expressions. One for the find and another for consistent, but this is far from the truth. For exam- the replace. ple, anyone who’s ever worked with Flare’s behind the scene code understands how complicated and For the find segment, we’re going to craft an ex- inconsistent it gets. Given the possible formations, pression that includes both tags at the same time. the machine generated code, and especially if Word That means it also includes the text between them, was ever involved, it seems impossible to find any- something we want to keep anyway. The find would thing. It’s not uncommon to see Flare’s HTML like: be (.*?)<\/span>. This expression can be broken up into three components

Who , (.*?), and class="span_2">steals my purse. We’ve seen the first part of steals trash; in the previous example. It class="span_Iago_reference">'tis some- finds text like span_1 or span_300. The last part thing, nothing;

catches the closing span. The interesting part is the Example 1: Sample HTML source code for the fol- middle expression of (.*?). The period was dis- lowing procedures. cussed as being a wild card that matches any character. The asterisk is the repetition marker for zero Clearly, this is messy code. Beyond some of our or more occurrences. So together .* finds zero or compulsion to have clean, organized code, this more occurrences of any character. You can see

48 2018 STC Technical Communication Summit Proceedings Using Regular Expressions with Madcap Flare: Putting Your Searches on Steroids how that the expressions matches everything in be- 1. Within a Flare project, open a topic file, tween the two tags. paste the Example 1 text into the body of the HTML in the Text Editor view. The problem is how to specify which closing tag to end with. In our example, there are four closing 2. Open Quick Replace (Home|Find and Re- span tags. At worst, the expression could find all the place|Quick Replace, or Ctrl-H). The Find characters from the first opening tag to the last clos- window opens in the top right of the topic ing tag. We’re interested in the characters from the page. first opening tag through only the first closing tag. 3. Enter (.*?)<\/span> in the greedy searches. By default, all searches are Find textbox. greedy, which means it will try to get the greatest 4. In the Filter Options button in the Find win- number of characters that match our pattern. In con- dow, select Regular Expressions. trast, a lazy search attempts to find the match with 5. Click the Find Next arrow in the Find win- the fewest number of characters. That’s the one we dow to select the text. This highlights the need. The question mark following a repetition nota- found text. While this step isn’t technically tion indicates to make the search lazy. And, yes, necessary for a find and replace option, it they double up on meanings for characters The re- does confirm the find portion. sult here is that our search matches the first closing span tag after the opening span tag. That would be 6. Click Replace Next in the Find window. This Who . It’s hard to makes the replacement and highlights the notice here but it includes a space after the word next find text. Who. 7. To speed this up, click Replace All. This replaces the remaining instances. For the replace segment, we’re going to selectively add back the body text we found. In the first case To use regex in Flare for multiple files: example, a replacement was made using fixed text, 1. Within a Flare project, paste the Example 1 (). Most of text into the body of at least two HTML files us are accustomed to using fix text with replaces. in the Text Editor view. But here, it’s going to be based on the actual found text. That is marked in the find expression by the 2. Open Find and Replace in Files parentheses around the term, such as (.*?). These (Home|Find and Replace| Find and Replace parentheses form what’s called a replacement in Files, or Ctrl-Shift-F). The Find window group. If there’s only one set of parentheses, that’s opens in the top right of the topic page. The the first replacement group, and noted in the find Find and Replace in Files panel opens to text as \1. If there’s a second set of parentheses the right. that would be noted as \2, and so. So for the find 3. Enter (.*?)<\/span> in the Who with Who , Find textbox. which still includes that space. Perform this opera- 4. Enter \1 in the Replace With textbox. tion three times, and the new HTML looks like: 5. Check Find in Source Code. Who steals my purse steals trash; 6. Select Regular Expressions from Search 'tis some- Type. thing, nothing; 7. Click Find Next. This highlights the next Example 2: Cleaned up HTML. found text. Much cleaner HTML. 8. Click Replace to make the selection. 9. To speed this up, click Replace All. This replaces the remaining instances. Making a Regex Find and Replace Other tools can make these changes too. One ex- Flare supports regex for both find and replace, and ample is NotePad++ (https://notepad-plus- single files and multiple files. plus.org/). This is an improved version of the vener- To use regex in Flare for a single file: able Windows NotePad but adds dozens of additional features, including regex. This is not a unique

2018 STC Technical Communication Summit Proceedings 49 Robert Delwood

product and to be clear there are plenty of similar 7. Click Replace in Files to make all the re- ones. To use regex in NotePad++: placements. Don’t worry yet, you’ll be asked for confirmation. 1. Within a Flare project, paste the Example 1 text into the body of an HTML file in the Text Editor view. Final Thoughts 2. Launch NotePad++. Regex is a powerful and versatile find and replace 3. Paste the Example 1 text into the body of tool. Because it is different than conventional find the HTML into the default open document, and replace, it requires thinking a little differently, likely named New1. that of patterns and not text. It is a rich language 4. To better the see text, you may use line with nuisance. That means two things. First, you al- wrapping by selecting View|Wrap. most never want to read someone else’s expres- 5. Open the Find dialog by clicking Ctl-F. sions. Depending how they craft them, it might be 6. Select the Replace tab. difficult to decipher. For example, [a-z0-9_\.- ]+@[\da-z\.-]+\.[a-z\.]{2,6} matches any e-mail ad- 7. Select Regular expression in the Search dress, although it may take a moment to figure out Mode panel. why. Second, it is crafting. Writing the correct ex- 8. Enter in Find What: (.*?)<\/span> ommend using an online regex tester, which shows 9. Enter in Replace with: \1 the results of the searches in real time, to build your 10. Click Find Next. The first match will get expression little by little. Then paste that expression highlighted. into your application. 11. Click Replace. The replaced text no longer This is not a tool to avoid or to be afraid of. I have has the span tags. shown with the samples above that a short expres- 12. To speed this up, click Replace All. This re- sion can do a lot. And with multipage options you places the remaining instances. can accomplish even more in less time. I feel when you start seeing the value of this, you’ll also start To do this for multiple pages: seeing opportunities to use them. 1. Within a Flare project, paste the Example 1 text into the body of at least two HTML files in the Text Editor view. Author Contact Information 2. Click Find in Files. 3. Make sure In all sub-folders is checked. Robert Delwood Lead API Documentation Writer 4. In the Directory textbox, enter a path, such WriteOnce.org as D:\Connectors\NewProject1\Content, or [email protected] click the ellipsis button (…) to navigate to the path. 5. Click Find All. This displays all the in- Author Biography stances found along the path. Robert Delwood is a programmer, writer, and pro- 6. This next step is the scary one. Be certain grammer-writer currently in Chicago but formerly that the replacement is correct for all the in- with NASA's Johnson Space Center in Houston. stances. While typically you have to save He's passionate about technical writing, procedural, each changed file, when making multiple in- conceptual, and for API documentation. With more stance changes, the replacements are than 18 years’ experience, he's written about and saved automatically. You would be correct documented topics from Windows kernel-level de- in thinking this could be a dangerous action, vice drivers and speech recognition APIs/SDKs for and it is. If you’re connected to a source Microsoft, to help desk procedures and application control system like Git, check in, push and manuals for the military. pull all the files first before making global changes. That way you can restore the en- He has two specializations: API documentation and tire project should a mistake be made. Microsoft Office automation. He’s documented APIs for more than a dozen years, and stresses the

50 2018 STC Technical Communication Summit Proceedings Using Regular Expressions with Madcap Flare: Putting Your Searches on Steroids

importance of upping everyone’s game from good documentation to great documentation. As a programmer-writer this includes writing original code samples, sample applications, and attention to detail in API reference pages. For Microsoft Office automation he believes every writing team can use a programmer-writer. Custom- ized tools can streamline any work process, in instances from weeks to literally minutes. It can also improve quality and perform task considered impossible by manual means. This can be accomplished internally, without involving the development department. He's authored three books. The newest is about writing great API documentation and is due out in summer of 2018. The Secret Life of Word (XML Press, http://xmlpress.net) is about Word's automation for technical writers, non-programmers, knowledge workers, or anyone who wants to do more things quickly with Word.

Dethrone the Content King! Culture is the True King Jamie Gillenwater

Although content surrounds us in our daily lives, culture is the true king. Culture ultimately drives content, so why aren’t we more focused on influencing our company’s culture. As an individual, you can influence change by considering hidden biases, talent acquisition and development, and leadership.

“Content is king.” Bill Gates predicted this com- customers, potential employees, and competitors monly accepted truth. Our entire world seems to review your company. volve around content. As communicators, this seems especially true. But what if I told you this was Hidden Biases a half-truth, or even a lie. Everyone has hidden biases. These biases are en- Culture is the true king. Culture might use content grained through our experiences as children and as a tool for shaping and demonstrating a culture adults. They might be the ideas that were passed to within a company, organization, or the general pop- us from our parents, teachers, and friends. Or these ulation, but culture is what ultimately influences biases could be based our personal experiences as change. teenagers and adults. Just as Gates suggested was true about content, is If you think you do not have any hidden biases, con- also true for changing company culture: “No com- sider taking the Implicit Association Test at pany is too small to participate.” https://implicit.harvard.edu/implicit/takeatest.html. How do you define company culture? According to This test will help you identify your preferences in a The War at Work, culture is “the formal or informal, variety of categories, including gender, weight, race, agreed upon, attitudes and behaviors that are either and religion (Figure 1). rewarded or penalized inside an organization.” With Because everyone has hidden biases, it is important that definition in mind, how can leaders and individ- to identify and address these biases. Once you uals change a company’s culture. identify your personal biases, you can begin to as- While there are many avenues for change, I will fo- sess how you make decisions within your company cus on three: that might limit achieving the greatest level of suc- 1. Hidden Biases cess possible. Do you dismiss comments made by an overweight person as less intelligent than com- 2. Talent Acquisition and Development ments made by a thin person? Are you more likely 3. Leadership to hire women than men to fill particular roles?

Why Culture? Talent Acquisition and Development You might be asking why company culture matters. Talent acquisition is an area that is greatly affected Your company culture is plastered everywhere, by hidden biases. With your knowledge of your own whether you want it to be or not. Employees and biases, how can you prevent them from influencing customers can now share insights into the way they your hiring decisions? Measure the required charac- are treated and expect to be treated publicly teristics for a specific position using data, not prefer- through websites, such as www.LinkedIn.com, ences. www.glassdoor.com, and www.indeed.com. These sites encourage users to provide as much detail as There are a variety of assessments that can be possible about what happens behind closed doors used to identify an applicant’s personal work prefer- in your company. These reviews influence the ways ences, strengths, weaknesses, and aptitude for the

52 Dethrone the Content King! Culture is the True King

Figure 1. Project Implicit screenshot available position. These assessments include the 90% of their time using their strengths and 10% of Smart Work | Assessments, StrengthFinder 2.0, and their time developing their weaknesses. DISC Personality Assessments. It is important to note that an assessment should not be the only tool used for hiring decisions, but it should be used be- Leadership fore the interview (Figure 2). When many people think about leadership, they fo- Once you have narrowed your applicant pool based cus on those at the top of the traditional company on experience and assessments, use behavioral in- hierarchy. However, the traditional hierarchy has terview questions to determine which applicant’s will transformed into a network of contributors, informal behave in a way that meets your company’s cultural leaders, and formal leaders. This new network re- expectations or will elevate your company culture at quires leadership at every level of professionals. In- an individual level. formal leaders create a healthy culture by their individual actions, which demonstrate the encouraged To change your company culture among existing behaviors. Formal leaders reinforce the desired cul- team members, it is important to set clear expecta- ture based on the way they reward or penalize their tions. If we revisit the definition of culture, talent de- team members’ behaviors. velopment is an opportunity to express “the formal, … agreed upon, attitudes and behaviors” that are expected in your company. Soft skills training and Conclusion team-building workshops allow leaders to help employees embrace and thrive within a company’s cul- As you reflect on your company’s current culture, tural expectations. assess how you can influence the culture as an individual contributor, either through formal or informal The assessments used for hiring can also be used leadership. Consider what suggestions you can for developing your existing team. It is important to make to formal leaders and how you can make understand each team member’s strengths, weak- changes to your own behaviors. nesses, motivations, and comfort in certain areas. With this knowledge, you can develop work plans that help each team member contribute within their expertise. Most employees thrive when they spend

2018 STC Technical Communication Summit Proceedings 53 Jamie Gillenwater

Figure 2. Sample results from a Smart Work | Assessment

Resources Kofman, Fred. Conscious Business (Boulder, CO: Banaji, Mahazarin and Anthony Greenwald. Blind Sound True), 2013. Spot: Hidden Biases of Good People (New Yok, Mattison, Seth and Joshua Medcalf. The War at NY: Bantam Books), 2016. Work (Middletown, DE: Self-Published), 2017. Gates, Bill. “Content is King.” Microsoft (January Project Implicit (2011). 1996). Republished at https://implicit.harvard.edu/implicit/takeatest.html. https://medium.com/@HeathEvans/content-is- king-essay-by-bill-gates-1996-df74552f80d9.

54 2018 STC Technical Communication Summit Proceedings Dethrone the Content King! Culture is the True King

Author Contact Information Jamie Gillenwater Consultant Transcend Text, LLC Greenville, SC 864.980.2521

Author Biography Jamie Gillenwater is an independent consultant who specializes in technical writing and talent development consulting. She helps companies ensure they hire the right people for the right job, and then helps ensure employees have the right tools to do their job well. Jamie is a Senior Member of the Society for Technical Communication. She serves on the STC Nominating Committee. She is also an author- ized trainer for the Certified Professional Technical Communicator (CPTC) Foundation exam.

Can You Hear Me Now? Podcasting as a Teaching Tool Jennifer Goode, PhD

Podcasting is one of the fastest growing areas of content production today. How can technical communication instructors capitalize on this rapidly expanding technology? This session will explain how students can develop technical skills, increase content knowledge and understanding, and refine communication skills as they create podcasts for their course projects. It will also introduce the tools and technology necessary to set up your own course podcasting project. Finally, the session will share instructor and student reflections from a recent course that used podcasts as part of a major course project.

What Is a Podcast? Equipment A podcast is an audio program, often produced as a To produce a basic podcast, you’ll need: series, that can be downloaded and played at any • A computer time. Podcasts are usually produced around a certain topic, and audiences can download individual • A microphone and speakers (or a headset podcasts or subscribe to the entire series. Think with a built-in microphone) about a podcast as a radio show—in a digital format • Access to the Internet that can be accessed anytime, anywhere. • Audio editing software (such as Audacity or Podcasts vary widely in format and subject matter, Adobe Audition) and listening to podcasts can be a great way to develop your expertise in a favorite subject or explore Media a completely new topic. Your options are numerous: learn how to start a new business, listen to an epi- To enhance your podcast, you may use: sodic fictional thriller, join the audience of a recent • Music TEDTalk, learn about application trends in Word- • Sound effects Press, or join your child in listening to an explanation of why we laugh. With podcasts, your morning • Cover art commute will never be the same! Publishing How Do I Create a Podcast? To publish or distribute your podcast, you will need: Creating a podcast isn’t as daunting as it may ini- • A media host tially seem. With a little planning and basic technol- • A website ogy, you can be podcasting in no time. Fortunately, several online resources exist to support you in the podcasting process. The Podcast Planning Host is a helpful resource for starting a new pod- Before you start, you should identify: cast. • Your topic • Your audience Why Use Podcasting as a Course • Your format Project? • Your podcast name Podcasts are a unique opportunity for student learning. Students have to analyze the context of the

56 Can You Hear Me Now? Podcasting as a Teaching Tool

content they are creating. The audience, the topic, What Would a Podcast Project Look the message, the solution, and the format all have to be strategically designed to fulfill the purpose of Like in My Course? the podcast. This exercise is similar to other audi- Students may create podcasts projects for a num- ence or needs analyses that would be conducted for ber of situations. Here are a few ideas: other types of content creation projects. • Student groups could create a podcast for Students can also explore the different communica- each chapter of the textbook. The class tion styles of podcasting, which vary slightly from could review the podcasts throughout the other forms of technical communication. For in- semester. stance, podcasting is strictly audial in nature, so ad- • A class might design a new podcast episode hering to oral speaking strategies is necessary. Ad- or series around a social issue or current ditionally, podcasts typically have repeat users (sub- event. scribers) with similar expectations, so selecting a common theme or format creates continuity across • Students could promote community events multiple episodes. Titles tend to take a different through a series of podcasts. structure in podcasting, and most podcasts include • Students might create a podcast series that episode notes with relevant references and web highlights the research projects at their uni- links from the broadcast. Again, The Podcast Host versity. The episodes might include inter- is a good resource for understanding communica- views with leading research faculty, as well tion nuances and applying them to podcast produc- as undergraduate and graduate research tion. students assisting with the projects. During their creation, podcasts provide a chance for • In a recent class, student groups were as- students to delve deeper into a particular area of signed to clients who had specific needs for content. Podcasting requires research and fore- interacting with organizational stakeholders. thought. It’s actually really difficult (if not impossible) Students created a series of eight podcasts to “wing” a good quality podcast episode. Thus, stu- for each client to promote key organizational dents have to pore over their source materials to objectives. create a strong content plan. This extra time can create the opportunity for deeper and broader un- What Are the Outcomes of a Recent derstanding of materials. Podcast Project? Podcasting also requires students to become mod- erately proficient with audio hardware, software, and In a recent undergraduate course entitled “Manage- publishing platforms. Several online tutorials exist ment of Social Media,” student groups developed a (YouTube, for instance) that students can use to proposal to serve a client’s programmatic communi- learn procedures and best practices for working with cation needs. In addition to creating a series of pod- professional microphones, using soundboards, edit- casts, students also developed content for popular ing in Adobe Audition, publishing to a host, and social media platforms—including Facebook, Twit- more. Podcasting helps students develop basic ter, LinkedIn, blogs, and Instagram—to develop a technical expertise in sound engineering. comprehensive social media communication plan for their client. Podcasts are archived for perpetual public use, so they have the ability to reach and impact future lis- At the end of the course, student feedback was col- teners for years to come. Students can revisit older lected via surveys. Here are a few of the notable podcasts from previous courses to learn about spe- findings and reactions: cial topics or unique events. Past podcasts can be • 11 out of 13 students (84.6%) cited podcast- reused in future semesters to introduce content, re- ing as their favorite media form to develop view case studies, recount an interview with a past during the class. guest speaker, or share another event that may not Students reported improved interviewing be replicable in the current semester. Podcasting • skills. preserves content for future use, which is particularly helpful when teaching a recurring course. • Students reflected on the importance of re- laxing, remaining conversational, using vocal inflection, and using stories when speaking publicly.

2018 STC Technical Communication Summit Proceedings 57 Jennifer Goode

• Students learned about scheduling, planning, and coordination while interviewing guest speakers and sharing a single sound Resources lab. The Podcast Host. • Students reported learning how to work with https://www.thepodcasthost.com/. new hardware (sound equipment) and software. Author Contact Information • Students found the work to be creative and interesting. Jennifer Goode • Students noted that scheduling interviews Instructor, Department of Technical Communication with multiple groups can be difficult when Mercer University there is only one sound lab available. 1501 Mercer University Drive Macon, GA 31207 Many students recognized the large time • 478.301.2149 commitment required to produce a single podcast. • Several students reported an increased in- Author Biography terest in engaging with podcasts in the fu- Jennifer E. Goode, Ph.D., is an instructor in the De- ture; a few mentioned audio technology as a partment of Technical Communication at Mercer specific career interest. University in Macon, GA. She is the founder and di- • One student noted, “I’m interested in be- rector of Mercer’s Distance and Online Teaching coming more transparent within writing and (DOT) Lab, a collaborative initiative to support fac- having a better ability of expressing ulty development needs in the area of online teach- thoughts. Podcasts were interesting and a ing and instructional design. Dr. Goode has previ- step outside of my comfort zone. However, ously served in corporate, government, and higher after doing so, I became more interested in education organizations in the areas of computer- developing better content.” based training, online course administration, and content management. Conclusion Dr. Goode earned her Ph.D. and M.Ed. in Human Resource Education from the University of Illinois at Podcasting offers unique opportunities and benefits Urbana-Champaign. She earned her B.S. in for the college classroom. With proper guidance, an Technical Communication from Mercer University. equipped lab, and a compelling purpose, students should find podcasting to be a rewarding experience that can further enhance their technical abilities and communication capacity.

Scoped Out! Sarah Kiniry

In Agile technical communication, it is vital to reliably estimate the needs of a project and to provide each estimate with the same scope. For projects that have not even been started yet, providing that estimate can be daunting. Maintaining that estimate in iterative development by multiple writers can be even more difficult … and even more vital to success. How do you define what goes into that estimate?

Embedding individual writers with teams can yield In addition to this issue, estimation of product great results. However, that same level of auton- needs, even on the level of individual user stories, omy can also create problems inconsistency. Dif- was lacking. Product owners were unsure how ferent writers, naturally, will document the same much effort was needed, and writers were some- features differently when they’re self-organized. times unable to give a clear picture on that front. Even without this problem, iterative development As a result, documentation needs were not in- by multiple writers can render any and all esti- cluded in overall project estimates. This, in turn, mates useless. Setting a global definition of done resulted in a lack of time allocated to reviews by in an easy-to-follow flowchart can solve this prob- developers, since they did not know what to ex- lem. cPanel’s decision-making flowchart helps to pect. The view of documentation as separate from generate a detailed list of needs and ensure con- the main line of development, already a problem sistency across projects. It can even help to “sell” in most software development environments, in- project needs and doneness to stakeholders. creased. Documentation was no longer part of the team’s responsibilities in their minds because those needs were not assessed in preliminary A Unique Problem planning. Interruptions to the predetermined pro- At cPanel, Inc., technical writers are embedded cess are rarely welcomed. directly with Agile teams. Because each writer only provides deliverables for one or two teams, One Product they can take part in team meetings and decisions in a way that often is not possible elsewhere. A main cause of inconsistencies, both in esti- Each writer is able to fulfill team needs without mates and final deliverables, was the widely-vary- worrying over bureaucracy. Writers themselves ing documentation sets being produced. One determine the needs of each project and com- team might create ten pages of documentation, a municate them to the teams. tutorial video, and internal training. The next team, working on a similar project, might only create five Each team develops its own features and projects pages of documentation and no videos or internal iteratively in an Agile environment. With that Agile training. framework comes autonomy through self-organization, which allows for a level of flexibility that is At first, these discrepancies were difficult to no- often impossible in other forms of project manage- tice. Each team’s final product seemed to be com- ment. Teams can change directions on the fly and plete when viewed alone. It was only when com- address sudden needs quickly. However, with so pared with other teams’ deliverables that the prob- many teams, autonomy can sometimes also intro- lem became apparent. The differences also hurt duce inconsistency. For cPanel’s Documentation morale within the department. Being human, com- department, these inconsistencies increased as parison between the writers themselves was inev- new teams were added. itable.

59 Sarah Kiniry

Figure 1: Three teams, three different sets of deliverables • Why did one writer spend so much time For cPanel’s Product Development department, on videos when they were unnecessary “done” is defined as: for another project? • Meets all project-specific acceptance crite- • Why were certain high-sensitivity docu- ria. ments not updated for the right projects? • Includes testing coverage. Why did they have to be corrected later by a different writer? • Meets development standards. • Why did customers have to ask for tutori- • Has been merged upstream. als on one feature when they had been • Includes acceptable amounts of documen- created during development for others? tation. Responding to customer requests after the fact As a high-level definition of done, this list is com- was not the best way to provide information. A prehensive. However, in practice, “acceptable user-centric perspective was vital to uncovering amounts of documentation” was clearly not the problem. Most users only see cPanel, the providing sufficient guidance. company, producing cPanel & WHM, the product. If everyone thought their documentation set was Each new feature is viewed as a part of the whole acceptable, who was right? If looked at from that rather than its own separate entity. Because users viewpoint, everyone was, since each Product only see one product, the variance in available in- Owner had accepted projects that used each formation was starkly apparent to them. scope. How can you determine an acceptable amount for a project without implementation de- Defining Done tails, and who was the best at doing so? The solution needed to come from the cPanel Documenta- In Agile development, the solution to this problem tion department and then trickle down to each Ag- is a “definition of done.” The definition of done de- ile team. fines each item that must be completed in order for anyone on the team to consider the project finished. A standardized definition of done can help A New Method teams to estimate project needs, and it can also serve as a stop sign if development outpaces the The answer was creating an internal, department- rest of the team. When providing project esti- specific definition of done. It was decided that a mates, the definition of done serves as the stand- simple bulleted list of nebulous requirements ard to meet. would not solve the problem permanently. The

60 2018 STC Technical Communication Summit Proceedings Scoped Out!

solution needed to incorporate ways of applying it personal and team preferences. The flowchart es- consistently: tablished the necessary baseline, leaving the nu- ance to the writer. • Because of the wide variety of projects writers encounter, it needed to be flexible. • For department morale and to use writers Dividing Product Areas to their full potential, it needed to preserve One of the main considerations for creating a defi- writer autonomy. nition-of-done flowchart is ease of use. cPanel’s • To ensure full coverage and avoid mis- documentation department maintains over 3,000 takes, it needed to highlight specific documents, far beyond the average person’s ca- highly-sensitive documents that needed pacity to memorize. An easy process that in- frequent updates. cluded finite details for highly-sensitive parts of • To make it accessible to new writers, it that documentation was vital, but a flowchart that needed to be self-explanatory and free included every possibility in one place was impos- from excessive technical terminology. sible. Division by document type meant duplica- tion of efforts since many documents fit multiple • To provide the best estimates for projects, it needed to be comprehensible to devel- audiences. opers, project managers, and others out- The only sensible method was to divide flowcharts side of the Documentation department. and decisions by areas of the product and their • Finally, to encourage use, it needed to be respective types of users. This left us with three easy and friendly. main categories: The creation of a decision-making flowchart al- • Graphical interfaces for both cPanel and lowed the department to collectively guide the WHM users. scope of provided documentation without remov- • Backend development and system admin- ing writer autonomy. By answering simple yes-or- istrator-targeted projects. no questions, writers could develop a concrete set • Integrations documentation for API and of tasks for any given project with only high-level other customization system users. information. Since each writer answered those questions themselves, they could use their own A fourth high-level chart brings all of these cate- technical understanding and professional exper- gories together for purposes of early-stage plan- tise to customize their scope to the team’s specific ning, when implementation details may not yet be needs. With the addition of optional items, writers available. could further tailor their estimates to their own

Figure 2: Division by audience type

2018 STC Technical Communication Summit Proceedings 61 Sarah Kiniry

Finding the Flow • Release Notes Dividing flowcharts was easy. Determining their • Internal training materials. exact flow posed a more difficult challenge. Be- • Interface documentation. cause the main pain point to solve was consistency of updates, we started from a list of • API functions. highly-sensitive documents. Some types, such as • Topic guides. tutorials, had some crossover, but for the most • YouTube videos. part, documentation like API functions or user in- • Script and file reference documentation. terface documentation was already clearly delineated. • Technically-focused marketing materials. • Internal documentation. We added a list of document types for each audience. Some types, such as tutorials, would ap- pear in each section, but API functions, user interface documentation, and most other types were already clearly delineated:

Figure 3: An early version of the high-level flowchart

62 2018 STC Technical Communication Summit Proceedings Scoped Out!

Because of cPanel’s focus on employee auton- projects. This testing identified several unexpect- omy, each department member’s opinions were edly-sensitive documents and some team- and taken into consideration. The first step for this was project-specific scenarios that needed to be ac- to poll each writer to find their existing scope for a counted for. given project. In addition to reinforcing autonomy, After the list of documents was finalized, they this helped to narrow down the flowchart contents were divided by the project elements they related further. Through comparison, we identified com- to. Documents about specific files and scripts mon documentation items across teams and pro- were only created or updated when a backend- jects. code project provided command-line options to Analysis of deliverables from one or two com- users. API function documentation and updates to pleted projects from each writer provided ample guides for creating plugins were only necessary data to begin refining the process. In addition to when those systems were altered. writers, stakeholder feedback needed to be in- These groupings allowed us to thin the list of doc- cluded. This included concerns from Technical uments and generalize some into overarching cat- Support, upper management, Product Owners, egories rather than granular document lists. The and select developers and QA analysts. only documents specifically referenced at this To do this, Agile team product owners and mem- point were our most sensitive documents, those bers of management were polled. Their assump- that couldn’t be categorized easily and were often tions about “appropriate amounts of documenta- missed as a result. tion,” in accordance with the company definition of done, were important in order to ensure later stakeholder buy-in. The resulting list of items from Tools and Design writers and stakeholders provided enough data to For additional ease of use, a simple format and begin designing the flowchart itself. Before attractive visual style were necessary. The ability flowchart contents were finalized, however, the to print the flowcharts as wall posters provided an item lists were tested on several in-development additional bonus for the new or less experienced

Figure 4: Flowchart creation in Omnigraffle

2018 STC Technical Communication Summit Proceedings 63 Sarah Kiniry

writers who would rely on them the most. The ad- we made sure to schedule presentations with dition of in-jokes, silly explanatory text, and each major group of stakeholders: cPanel-specific jargon helped it to match cPanel’s • The Documentation department manager. casual and friendly corporate culture. A relaxed tone helped to prevent the charts from feeling re- • The Documentation department. strictive and bureaucratic, while attention was still • Product Owners. given to avoiding jargon that wouldn’t be learned • Scrum Masters. during the initial onboarding process. • Upper management. To do this, we used Omnigraffle to lay out • The Technical Training team and Tech- flowcharts, though there are several other options, nical Support. such as Draw.io, that could also have been used. The tool itself also eased the task of chart crea- We had to fight for many of these meetings, par- tion and ensured that future updates would be ticularly for meetings with management, but, over- painless, even if they were made by writers who all, the feedback was positive. Even better, we had not been involved in the initial creation profound that the flowchart presentations did not just cess. elicit buy-in. The design of the chart was matched as closely Many of these groups, even writers in the Docu- as possible to existing cPanel branding standards, mentation department, expressed surprise at the including the company mandate to be “quirky,” number of tasks that were generated by using the even though it was internal. The flowcharts used flowchart, which, of course, exposed one of the cPanel’s official fonts and branding colors and in- core causes of inconsistency. Many stakeholders cluded small elements of cPanel’s culture (such said that they were already able to understand po- as an obsession with food). tential project needs and estimates more easily simply by viewing the flowcharts, even if writers The branding color palette was used to highlight were not yet involved in the project. Sometimes, flow items (cPanel’s bright orange logo color) and this better understanding directly resulted in a make individual task items easily identifiable and writer being assigned to a project when there oth- positive-looking (cPanel green). Items in grey pro- erwise would not have been one. vided optional or helpful information without distracting from the flowchart’s main use. This color They also served as an excellent tool for evange- palette helped to increase the sense of it being a lizing to the rest of the company the importance formal and necessary part of the process rather and capabilities of the Documentation depart- than a suggestion. ment. One document per sprint was not all that we could do, and one document per sprint was As the final product was presented to various not all that was necessary. Documentation could stakeholders to get their buy-in, unanticipated ad- not be viewed through the lens of only a single ditional feedback was generated. Most of this project. feedback assisted in making the chart accessible to newer writers or to outside stakeholders who Instead, it needed to be viewed in the context of were not already familiar with the documentation the product as a whole and its myriad features. set or departmental culture. In the end, four itera- This holistic viewpoint has helped the flowcharts tions over the finalized chart were made as it was transcend their original use case. It has started presented to various groups. the slow process of a cultural shift from viewing documentation as a sideline item to viewing it as an integral part of the product. The more visibility Sell It! the process has, the more it will be respected. Without stakeholder buy-in, the results of this process would have been worthless. Because of this,

64 2018 STC Technical Communication Summit Proceedings Scoped Out!

Figure 5: The final high-level flowchart

2018 STC Technical Communication Summit Proceedings 65 Sarah Kiniry

Figure 6: The final user interface flowchart

66 2018 STC Technical Communication Summit Proceedings Scoped Out!

In a past life, Sarah was a stage manager and audience development manager at several of Hou- ston’s professional theaters and performing arts Author Contact Information venues. She believes that technical communica- Sarah Kiniry tion is really just another art and that documenting Technical Writer II an interface isn’t that much different from telling cPanel, Inc. any other story. 2550 North Loop West Ste 4006 Houston, TX 77092 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 development team, as well as participating in content strategy and other initiatives for the company as a whole.

Science-Based Page Design for Technical Communicators Tina M. Kister

Good page design is an essential component of effective technical communication. It ensures that information is easy to find, read, understand, and remember. It can elicit an immediate and positive visceral response, which also facilitates effective communication. Good page design is a discipline that can be achieved by applying combining a deep understanding of human visual perception with a logical, mathematical, and iterative approach.

and we form immediate impressions that are difficult What is Design? to dispel (Lindgaard et al., 2006; Sillence et al., Fundamentally, design is a simple and neutral con- 2004). Effective visual design is so powerful that it cept. As a noun, design refers to the arrangement of can instill persistent trust and facilitate engagement, things (features). As a verb, design refers to the act despite known issues with usability and content (Sil- of arranging things. Design, in and of itself, is nei- lence et al., 2004; Tractinsky et al 2000). ther good nor bad—neither high-quality nor low- At the same time, it is critical to acknowledge that quality. As society has evolved since the Industrial design and content are inseparable, and that design Revolution and throughout the Information Age, the is not a substitute for quality content. A recent study concept of design has become more complex and of the effects of design and content on users of nuanced (Buchanan, 1992). Design exists “within health-care websites showed that design factors the dynamic flow of experience and communication, were most important to users during the initial emphasizing rhetorical relationships among… de- stages of engagement (94% weighted importance), signers, audiences, and the content of communica- while content factors were most important to users tion” (Buchanan, 1992, p. 12). Design involves a during the later stages of engagement (83% complex dynamic interaction between art, craft, and weighted importance; Sillence et al., 2004). science. While art is a form of self-expression, design is user-centered. While craft is concerned with Design is an integral component of all information the making of things, design is concerned with the development, and the scientific concepts behind hu- using of things. While science is based on intellec- man perception form the basis of best practices in tual, systematic observation to facilitate knowledge, design. With a deep understanding of the visual pro- design is based on the application of intellectual, cess, we can more successfully make design deci- systematic observation to facilitate a response. At sions that ensure technical content is easy to find, its core, design is problem-solving (Dorst, 2011; easy to read, easy to understand, credible, and vis- Friedman, 2002), and the qualitative nature of de- ually appealing. sign is determined by its effectiveness in solving problems for the user. Overview of Human Perception (Visual Information Processing) The Power of Design Perception occurs in two basic phases (Goldstein, The power of design in technical communication is 2010, p. 5): sensation and translation. These two often overlooked and undervalued. We tend to fo- phases are also called extraction and classification cus on the details of text-based content and fail to (Marr, 1982) and bottom-up (stimuli-based) and top- cultivate a deep understanding of how design and down (knowledge-based) processing (Goldstein, content work together to create effective communi- 2010). cation deliverables (Virtaluoto, 2013). We process visual information very quickly (John- son, 2014; Lindgaard et al., 2006; Tsotsos, 1990),

68 Science-Based Page Design for Technical Communicators

Sensation each of which responds to different frequen- cies in the visible spectrum of light. For sim- Sensation refers to the anatomical and physiological plicity, these are classified as either red, processes of receiving visual stimuli from the out- green, or blue (Goldstein, 2010). side world (Figure 1). During this phase, light enters through the cornea. It then passes through the pu- The photoreceptors then convert one form of energy pil—the hole in the middle of the iris. The lens then (light) into another form of energy (electrical) so that focuses the light on the retina, which contains the our nervous system can process the information photoreceptors. Stimuli are concentrated on an area (Goldstein, 2010). The electrical energy then travels of the retina called the fovea. The fovea is the area through the optic nerve to the primary visual cortex, of the retina that allows us to perceive with the high- located in the occipital lobe (at the back of the est possible resolution (Chen and Choi, 2008; Gold- brain). stein, 2010) because it contains the highest concentration of photoreceptor cells (Purves et. al, 2001). Translation The density of photoreceptor cells in the fovea is about 200 times greater than in the rest of the retina Translation refers to the neurological and chemical (Purves et. al, 2001). processes that occur in the brain that create meaning. Note that this phase is most often referred to as perception, and I instead use the term translation to differentiate it from the perception process as a whole, and to allude to the nature of the process, which is to move information from one place (the brain) to another (the mind). There are a few prevalent frameworks for understanding how stimuli are processed and interpreted (Purves et. al, 2014). Central to these frameworks is the concept that we don’t see what actually exists in the world: “…biological visual systems cannot measure or otherwise access the properties of the physical world.” (Purves et al., 2014). These frameworks are not necessarily mu- tually exclusive, and all rely the basic concept that perception is not a simple, anatomical conse- quence of retinal stimulation, but is a combination of complex, interpretive processes that occur both Figure 1. In visual perception, light enters the eye in sequence and in parallel (Treisman and Gormi- through the cornea, passes through the pupil, and can, 1988). then through the lens. The lens focuses the light on Generally speaking, translation occurs in three the retina, where it appears upside down and back- phases: wards. Cells in the retina then transform the light into neurochemical impulses that are sent to the 1. Feature Detection (Selection)—During this brain (University of Minnesota, 2015). phase, visual information is broken up and classified by specialized neurons that re- There are two types of photoreceptor cells on the spond to specific features, such as edges, retina that respond to light (Goldstein, 2010, Ware lines, and angles. Some features in the vis- 2011): ual field are basic to perception and are de- • Rods—Rods facilitate vision in low-light tected without conscious attention or focus (nighttime) conditions and are associated (Mack et al., 1992; Goldstein, 2010). with peripheral vision and motion (Goldstein, 2. Organization (Mack et al., 1992)—Visual in- 2010; Nave, 2017; Ware, 2011). formation is reorganized and reassembled • Cones—Cones allow us to perceive edges, in the visual cortex so we can make sense shadows, and contrast, and to discern be- of it. While little is understood about exactly tween stimuli based on shape, position, and how the process works, there are numerous color. There are three types of cone cells, widely accepted principles that describe the

2018 STC Technical Communication Summit Proceedings 69 Tina M. Kister

various phenomena related to organization, The elements of design include: including the framework known as the Ge- • Line stalt principles of visual perception. • Shape 3. Interpretation—The identified objects are given meaning, which directly and strongly • Color influences both our ongoing perception and • Value our actions. • Form • Texture Design Elements • Space During the sensation phase, cones are the photore- Texture is an example of a traditionally taught de- ceptor cells that allow us to perceive edges, shapes, sign element that is, in fact, created by the combina- shadows, and contrast. There are three types of tion of shape, color, and position (Figure 3; Landy cone cells, each of which responds to different fre- and Graham, 2004). quencies in the visible spectrum of light (classified, for simplicity, as either red, green, or blue; Gold- stein, 2010; Purves et al., 2001). Design Principles Because of the way that our retinal photoreceptor During the translation phase, visual stimuli are pro- cells work, we are able to perceive three fundamen- cessed in terms of heuristics such as the Gestalt tal types of visual information (Figure 2): principles of visual perception, and/or according to stored knowledge of the properties and conditions • Shape that exist in the world. (Purves et al., 2014). The • Color Gestalt principles of visual perception describe the • Position (including depth, which is position phenomena by which we perceive whole, struc- in three dimensions) tured, meaningful objects, despite the fact that visual stimuli do not coincide with the actual properties These three fundamental types of visual information that exist in the world (Purves et al., 2014). (For are the building blocks of design, and—either alone more information about the Gestalt principles of vis- or combined—form the basis of the elements of de- ual perception, see Golombisky and Hagen, 2013; sign that are taught in basic design classes (Golom- Johnson, 2014; University of Minnesota, 2015; bisky and Hagen, 2013). Ware, 2011.)

Figure 2. The three fundamental types of visual information (shape, color, and position) are the building blocks of design, and—either alone or combined—form the basis of the elements of design that are taught in basic design classes (Golombisky and Hagen, 2013).

70 2018 STC Technical Communication Summit Proceedings Science-Based Page Design for Technical Communicators

Figure 5. Multistability—When sensory clues are ambiguous, our perception of images alternates so Figure 3. Texture is one of the basic design ele- that we are able perceive two different and wholly ments taught in design classis, and is an effect cre- complete images. ated by the combination of shape, color, and position (Landy and Graham, 2004). The Gestalt principles of visual perception include reification, multistability, prägnanz, the law of invariance, the law of similarity, the law of proximity, and many more. (See Figures 4-9).

Figure 6. Prägnanz—We tend to recognize and prefer things that are simple and clear, rather than Figure 4. Reification—Our mind creates visual ele- complex and difficult to understand. Things that are ments that don’t exist in order to create meaning. simple and clear are easier to perceive, process, That is, our experience of the stimuli contains more and remember. When presented with complex vis- explicit information than the sensory stimuli on ual information, our minds simplify it by classifying it which it is based. according to what we already know and understand. Patterns take precedence over individual elements. The simplest organization that requires the least cognitive effort will emerge as the final perceived figure. Our minds take shapes that could be incredibly complex (if we interpreted them differently than we do) and simplify them. The simplest organization that requires the least cognitive effort will emerge as the final perceived figure.

2018 STC Technical Communication Summit Proceedings 71 Tina M. Kister

Figure 9. Law of Proximity—We intuitively associate things that are close to one another and classify them as related. Conversely, we separate things Figure 7. Law of Invariance—We have the ability to that are farther apart into separate categories, de- identify certain visual percepts regardless of various spite other common characteristics. changes, such as changes in size, orientation, color, and even actual feature. But, as a designer, These are just a few of the heuristics that allow us the more you deviate from what readers/users ex- to create meaning from visual stimuli. These heuris- pect, the more time it will take for the reader to pro- tics form the basis of the principles of design that cess the information. If you push it too far, it may are taught in basic design classes (Golombisky and simply become visual nonsense. Hagen, 2013). The principles of design include: • Balance • Contrast • Emphasis • Movement • Pattern • Rhythm • Unity These principles, in turn, are the basis for ensuring effective page designs that allow users to scan, read, retain, and use technical information.

Text Text is a page element with a host of characteristics Figure 8. Law of Similarity—We intuitively group (Figure 10) and individual attributes that affect a things that are similar in size, shape, color, orienta- user’s response to page design (Bernard et al, tion, etc. 2001; Carter et al., 2018; Golombisky and Hagen, 2013; Juni and Gross, 2008; Labrecque and Milne, 2012). The treatment of text in page design (typography) is critical to effective communication, and the nuances of text and its attributes call for special attention and study, which is outside the scope of this presentation.

72 2018 STC Technical Communication Summit Proceedings Science-Based Page Design for Technical Communicators

Figure 10. This diagram, which shows the anatomy of a font, demonstrates how complex typography is. Key: 1) x-height, 2) ascender line, 3) apex, 4) baseline, 5) ascender, 6) crossbar, 7) stem, 8) serif, 9) leg, 10) bowl, 11) counter, 12) collar, 13) loop, 14) ear, 15) tie, 16) horizontal bar, 17) arm, 18) vertical bar, 19) cap height, 20) descender line. (Source: https://commons.wikimedia.org/wiki/File:Typographia.svg; Flanker. Ty- pographic font designed by Flanker, named Imperator; public domain via Wikimedia Commons)

content, colors, font, and audience), and logic is a Application: General Guidelines very useful tool in making decisions. Visual design is complex; there are no simple, uni- Conditional reasoning is a particularly useful type of versal recipes for successful design (Parker, 2003; logic. Conditional reasoning refers to a logical pro- Johnson, 2014). Effective visual design depends cess in which you make an inference based on a many factors, including the materials, the message, premise, or use “if-then” scenarios (Markovits and the media, the technology, and—of course—the infi- Barrouillet, 2002). This is the same process we reg- nitely variable human audience. ularly use for content-development: if this is a com- While a deep understanding of human visual per- pound modifier, then we use a hyphen; if this is a ception does provide a foundation for making spe- proper name, then we use initial capital letters. cific design decisions (such as whether to left-align, Because page design is primarily based on the rela- right-align, or justify text), those types of decisions tionship between elements, and many elements are will always depend, to some degree, on the specific required (such as using company colors), condi- project you are working on. Because there are so tional reasoning can be used to guide page-design many variables, it’s just as important to learn how to decisions in relation to the given elements (Figure think about design and how to make design deci- 11). For example, if a page layout includes two col- sions as it is to learn the “rules” of page design. umns and the content includes bulleted lists, then it There are many resources that provide specific it’s best use additional space between paragraphs, guidelines, some of which are better than others rather than a first-line indent. This is because, with (e.g., Golombisky and Hagen, 2013). It is critical to two-column content, the user’s eye must find the cultivate a deep understanding of how humans pro- beginning of each line more frequently than with cess visual information and to take a logical, mathe- one-column content, and because bulleted lists, matical, and iterative approach, in order to decide which should be indented to show the subordinate which guidelines to follow to create effective page relationship of the content and convey a clear hier- designs. archy, also require the user’s eye to find the beginning of each line, which is not located along the left Logic edge of the content. Logical reasoning is critical in page design, because Logic is particularly important in regard to infor- it helps you make decisions that are based on mation typing, which is a necessary and integral known parameters and valid principles. In design, part of both content-development and design. particularly in page design for technical communication, the goal is to solve a particular problem (ensuring that information is easy to find, read, understand, and remember) given the requirements and restrictions imposed by the conditions of the project (i.e., business objectives, media, technology,

2018 STC Technical Communication Summit Proceedings 73 Tina M. Kister

Conditional reasoning is a very helpful form of logic in page design because each design decision includes so many variables. In this example, conditional reasoning might include: “If I am going to use two columns for content that includes bullets (both of which require the user to do more work in finding the beginning of each line than content in a single column without bullets), then I should not use a first- line indent, because the first-line indent is harder to find and is too easily confused with the indentation of the bulleted list.”

Information Typing Information typing is the process of assigning roles to units of content and design. Information typing is so ubiquitous that it is taught an elementary school level (e.g., the difference between a topic sentence and a concluding sentence), and it is also a fundamental component of many more advanced information-development frameworks, such as Darwin Information Typing Architecture (DITA) and HTML/XML and CSS. These frameworks consist “of a set of design principles for creating "information- typed" modules at a topic level....” (Day et al., 2005) Variously referred to as content modeling, information modeling, tagging, information mapping, and more, information typing is used in many communication sub-disciplines, including web design, proposal development, content strategy, technical communication, knowledge management, information architecture, data analysis, user interface design, and more. In terms of page design, information typing refers to identifying the various discrete page elements (e.g., title, heading, footer, list), and then assigning attributes to each type based on the role of the content or design unit within the document. For example, the role of a heading is to act as a signpost for users and to facilitate scanning, provide context, convey relationships, and direct the user’s attention. (See Figures 12a-12h.) Because we know the role of headings within a document, we can make design decisions that ensure headings are effective in that role.

Figure 11. Conditional reasoning

74 2018 STC Technical Communication Summit Proceedings Science-Based Page Design for Technical Communicators

Figure 12a. Information typing refers to the process of classifying bits of information according to the role they play. In page design, classifying a unit of information can tell you how it should be treated visually. For example, let’s say you have a block of text and you already know that your body text will be Open Sans font, and you need to design headings.

Figure 12b. Because you know that headings should use title case, you can capitalize the first word of each heading.

Figure 12c. Because you know that headings should guide the reader in quickly finding information, you know that the headings need to attract the eye more than the body text. Therefore, you can make the headings larger than the body text.

2018 STC Technical Communication Summit Proceedings 75 Tina M. Kister

Figure 12d. Because the difference is not big enough to be visually effective yet, you can make the headings bold.

Figure 12e. Because these headings represent different heading levels, and you need to differentiate between the different levels, you can make each higher-level heading level progressively larger. In this case, the lowest-level heading is 2 points larger than the body text, the mid-level heading is 4 points larger, and the top-level heading is 8 points larger.

Figure 12f. To segregate each block of information more clearly, you can add white space above each heading so the design conforms more closely with the Gestalt principle of proximity. In this case, each heading has 12 points of white space above it.

76 2018 STC Technical Communication Summit Proceedings Science-Based Page Design for Technical Communicators

Figure 12g. To further differentiate between each level and to reinforce each heading’s relationship with the text that follows, you can add a progressively greater amount of white space above the two higher-level headings. In this case the mid-level heading has an additional 6 points, and the top-level heading has an additional 12 points.

Figure 12h. Finally, to ensure that each heading is surrounded by enough white space that they attract the eye, while maintaining the visual proximity to the body text, you can progressively increase the amount of white space below each heading. In this case, the white space below each heading has been increased by 2 points, so the lower-level heading has 2 points below it, the mid-level heading has 4 points below it, and the top-level heading has 6 points below it. ensure consistency and precision. (See Figures Styles 12a-12h.) Too many designers, particularly amateur Styles are a feature available in most programs designers, estimate, or “eyeball” page design com- you’ll use for page design, and they are an essential ponents such as size, shape, alignment, and color. information-typing tool for ensuring consistency, Programs used for page design allow you to enter saving time, collaborating with others, and maintain- numerical values for color, size, position, and many ing documents. Styles allow you to save a set of at- other attributes (Figure 13). Using numerical values tributes and apply them to a content or design unit allows you to make design decisions that are based with a single click. More sophisticated design pro- on precise calculations and to ensure they are im- grams allow designers to save numerous types of plemented consistently. A mathematical approach styles, including paragraph, character, and graphic helps ensure a positive user response at an uncon- styles. scious level, as well as a conscious level—slight discrepancies and mistakes can increase the time it Math takes to process information, confuse the user, and damage credibility. Taking a mathematical and numerical approach is important in page design because it helps you

2018 STC Technical Communication Summit Proceedings 77 Tina M. Kister

Many programs also include tools that help you en- without meaning can both slow information pro- sure precise alignment and distribution without hav- cessing and create a sort of cognitive discord (even ing to enter numerical values. unconsciously) that detracts from the effectiveness of the design. Unintentional design can cause confusion, clutter, and even contradict your intended meaning, which can negatively impact credibility.

Golden Mean One of the most useful mathematical concepts in design is the Golden Mean (or Golden Ratio). The Golden Mean is a ratio that, for some reason, is uni- versally appealing and found ubiquitously in nature. It’s another concept that is part of most basic design classes. The Golden Ratio describes a relationship: “as the whole… is to the greater… so is the greater to the lesser” (Figure 14; Livio, 2008).

Figure 14. The Golden Mean is a very mathematical concept used frequently in design, and it can be very useful in making design decisions, such as where to position an element on a page. The ratio is approximately 1.618, or 37.5 to 62.7, or about 60/40. In practical terms, the ratio is approximately 1.618, or 37.5 to 62.7, or about 60/40. So, anytime you Figure 13. Using numerical values and math to de- need to make a decision that includes a ratio, a po- termine style attributes helps ensure consistency, sition, a proportion, or scale, you can start with the focus on intentional meaning, and apply the concept 60/40 rule. While the sort of mystical and magical of Just-Noticeable Difference. Many programs also qualities ascribed to the Golden Ratio have likely include tools that help you ensure precise alignment been overstated in popular culture, as well as in me- and distribution without having to enter numerical dia and design studies (Markowsky, 1992), it does values. provide a useful starting point for making design decisions. Using math also helps ensure that your design elements have intentional meaning, because it forces Just-Noticeable Difference you to think consciously and systematically about your design decisions. Taking a mathematical approach also allows you to adhere to the concept of Just-Noticeable Difference Intentional Meaning (Figure 15). While you should always use contrast (in shape, color, and position) to create meaningful Make sure your design choices have a purpose and visual distinctions, it is important never use more an intentional meaning. Because humans innately contrast than necessary. Just-Noticeable Difference assign meaning to everything, with a particular at- is a scientific term in perception studies that refers tention to difference and contrast, then differences to the minimum amount of difference that a user can

78 2018 STC Technical Communication Summit Proceedings Science-Based Page Design for Technical Communicators

Figure 15. Just Noticeable Difference refers to the minimum amount of difference that a user can perceive. In page design, it’s important to use contrasts that are “definite, effective, and minimal” (Tufte, 1997, p. 73). perceive. In page design, “Make all visual distinctions as subtle as possible, but still clear and effective... In designing information…the idea is to use just notable differences, visual elements that make a clear difference but no more—contrasts that are definite, effective, and minimal” (Tufte, 1997, p. 73).

Test the Outliers and Refine Finally, it’s important to test your page designs with content elements that are at the extremes of what you will include, and then to refine your designs to accommodate those outliers. This is particularly important when working with large documents, a set of documents, and in a team setting. In the initial stage of page design, it’s easy to create design elements that work well with placeholder text or with a specific unit of actual content. However, it’s important to make sure that design choices are also effective when used with so-called outlier content—that is, content that pushes the limits of design. So, for example, a heading that looks great when it’s less Figure 16. It’s important to test your page designs than one line may look terrible when it’s two or more with content elements that are at the extremes of lines (Figure 16). Body text that is readable in short what you will include (such as very short and very paragraphs may be difficult to read in long para- long headings), and then to refine your designs to graphs. accommodate those outliers.

2018 STC Technical Communication Summit Proceedings 79 Tina M. Kister

Conclusion Chitturi, R., R. Raghunathan, and V. Mahajan. “Delight by Design: The Role of Hedonic Versus This paper contains just a few examples and a cur- Utilitarian Benefits.” Journal of Marketing 72.3 sory discussion of how some of the physiological (2008): 48-63. and psychological processes of visual human per- Eagleman, D. Incognito: The Secret Lives of the ception relate to effective page design. There are Brain (New York, NY: Pantheon Books), 2011. many, many others, and they are both immensely Holtzblatt, K. (2011). “What Makes Things Cool? interesting and directly relevant to effective page Intentional Design for Innovation.” interactions design. The more thoroughly you understand how 18.6 (2011): 40-47. humans perceive and process information, the more effectively you can make design decisions at the Kurt, S., and K. K. Osueke. “The Effects of Color on time of need. the Moods of College Students.” SAGE Open (2158244014525423) 4.1 (2014). Shaikh, A. D., B. S. Chaparro, and D. Fox. Recommended Reading “Perception of Fonts: Perceived Personality Traits and Uses.” Usability News 8.1 (2006): 1- Because page design (like content development) is 6. such a dynamic process, it requires continuous learning. There is a wealth of information available Valdez, P., and A. Mehrabian. “Effects of Color on in “other” areas of technical and business communi- Emotions.” Journal of Experimental Psychology: cation, such as graphic design, web design, user-in- General 123.4 (1994): 394. terface design, instructional design, industrial de- Voss, K. E., E. R. Spangenberg, and B. Grohmann. sign, presentation design, scientific communication, “Measuring the Hedonic and Utilitarian marketing, and human-computer interaction. The Dimensions of Consumer Attitude.” Journal of basic principles that underly effective page design in Marketing Research 40.3 (2003): 310-320. these areas are the same as those for technical Wong, D. M. The Wall Street Journal Guide to communication. Information Graphics: The Dos and Don'ts of Presenting Data, Facts, and Figures (New York, It’s vital to take an approach that is guided by intel- NY: W. W. Norton and Company), 2010. lectual curiosity, a healthy skepticism, and a deep understanding of how humans process visual information. References I highly recommend the following books: Bernard, M., C. H. Liao, and M. Mills. The Effects of • Designing with the Mind in Mind by Jeff Font Type and Size on the Legibility and Johnson Reading Time of Online Text by Older Adults (CHI EA '01, March 31-April 5 2001). • Slide:ology: The Art and Science of Cre- ating Great Presentations by Nancy Du- Buchanan, R. “Wicked Problems in Design arte Thinking.” Design Issues 8.2 (Spring 1992), 5- 21. Carter, R., S. Maxa, M. Sanders, P. B. Meggs, and B. Day. Typographic Design: Form and Resources Communication, 7th ed. (Hoboken, NJ: John Wiley and Sons), 2018. Bellizzi, J. A., A. E. Crowley, and R. W. Hasty. “The Chen, K.-c., and Choi, H. J. “Visual Attention and Effects of Color in Store Design.” Journal of Eye Movements.” (2008). Retailing 59.1 (Spring 1983): 21-45. http://www.ics.uci.edu/~majumder/vispercep/ Biederman, I., and E. A. Vessel. (2006). “Perceptual vis ualattentionpaper.pdf. Pleasure and the Brain: A Novel Theory Day, D., M. Priestley, and D. Schell. “Introduction to Explains Why the Brain Craves Information and the Darwin Information Typing Architecture.” Seeks It Through the Senses.” American developerWorks (2005). Scientist 94.3 (2006): 247-253. http://people.cs.vt.edu/~kafura/CS6604/Papers/ Darwin-Information-Typing-Architecture.pdf.

80 2018 STC Technical Communication Summit Proceedings Science-Based Page Design for Technical Communicators

Dorst, K. (2011). “The Core of ‘Design Thinking’ and Visual Information (Cambridge, MA: MIT Press), Its Application.” Design studies 32.6 (2011): 1982. 521-532. Nave, C. R. (2017). “Light and Vision.” Duarte, N. Slide:ology: The Art and Science of HyperPhysics. http://hyperphysics.phy- Creating Great Presentations (Sebastopol, CA: astr.gsu.edu/hbase/ligcon.html#c1. O'Reilly Media), 2008. Parker, R. C. Looking Good in Print (Scottsdale, AZ: Friedman, K. “Theory Construction in Design Paraglyph Press), 2003. Research: Criteria, Approaches, and Methods.” Purves, D., Monson, B. B., Sundararajan, J., and Design Studies 24.6 (2002): 507-522. Wojtach, W. T. (2014). How biological vision Goldstein, E. B. (2010). Sensation and Perception, succeeds in the physical world. Proceedings of 8th ed. (Belmont, CA: Thomson Wadsworth), the National Academy of Sciences, 111(13), 2010. 4750-4755. doi:10.1073/pnas.1311309111. Golombisky, K., and R. Hagen. White Space Is Not Sillence, E., P. Briggs, L. Fishwick, and P. Harris. Your Enemy: A Beginner's Guide to Trust and Mistrust of Online Health Sites. Communicating Visually Through Graphic, Web (SIGCHI Conference on Human Factors in and Multimedia Design (New York, NY: Taylor Computing Systems, April 24-29, 2004). and Francis), 2013. Tractinsky, N., A. S. Katz, and D. Ikar. “What Is Johnson, J. Designing with the Mind in Mind: Simple Beautiful Is Usable.” Interacting with Computers Guide to Understanding User Interface Design 13.2 (2000): 127-145. Guidelines, 2nd ed. (Waltham, MA: Elsevier), Tsotsos, J. K. “Analyzing Vision at the Complexity 2014. Level.” Behavioral and Brain Sciences 13.3 Juni, S., and J. S. Gross. “Emotional and (1990): 423-445. Persuasive Perception of Fonts.” Perceptual Tufte, E. R., S. R. McKay, W. Christian, and J. R. and Motor Skills 106.1 (2008): 35-42. Matey. Visual Explanations: Images and Labrecque, L. I., and G. R. Milne, G. R. “Exciting Quantities, Evidence and Narrative (Cheshire, Red and Competent Blue: The Importance of CT: Graphics Press), 1997. Color in Marketing.” Journal of the Academy of Virtaluoto, J. “’It’s a Strange Little Business’—Issues Marketing Science 40.5 2012): 711-727. in Technical Communication.” AFinLA-e Sovelta Landy, M. S., and N. Graham. “Visual Perception of van Kielitieteen Tutkimuksia 5 (2013): 200-213. Texture” in L. M. Chalupa and J. S. Werner, Ware, C. Visual Thinking for Design. (Amsterdam, eds. The Visual Neurosciences (pp. 1106- Netherlands: Elsevier Morgan Kaufmann), 2011. 1118). (Cambridge, MA: MIT Press), 2004. Lindgaard, G., G. Fernandes, C. Dudek, and J. Brown. “Attention Web Designers: You Have 50 Milliseconds to Make a Good First Impression!” Behaviour and Information Technology 25.2 (2006): 115-126. Livio, M. The Golden Ratio: The Story of Phi, the World's Most Astonishing Number (New York, NY: Broadway Books), 2008. Mack, A., B. Tang, R. Tuma, S. Kahn, and I. Rock. “Perceptual Organization and Attention.” Cognitive Psychology 24.4 (1992): 475-501. Markovits, H., and P. Barrouillet. “The Development of Conditional Reasoning: A Mental Model Account.” Developmental Review 22.1 (2002): 5-36. Markowsky, G. “Misconceptions about the Golden Ratio.” The College Mathematics Journal 23.1 (1992): 2-19. Marr, D. Vision: A Computational Investigation into the Human Representation and Processing of

2018 STC Technical Communication Summit Proceedings 81 Tina M. Kister

Author Contact Information Tina M. Kister Founder, Consultant Nanatoo Communications 10151 University Blvd. #254 Orlando, FL 32817 435.260.1565 [email protected]

Author Biography Tina M. Kister is the founder of Nanatoo Communi- cations, a company dedicated to taking an interdis- ciplinary approach to improving information-development processes. Kister’s work experience spans a range of fields and industries, including Depart- ment of Defense, Department of the Interior, professional art, advertising, journalism, the sciences, health care, software, instructional design, process improvement, project management, and more. With a degree in Communications, graduate studies in Online Communications, and certifications in technical communication (CPTC), project management (PMP), proposal management (APMP), and content strategy, Kister provides a rare perspective that syn- thesizes best practices across traditionally siloed areas of business communications.

UI/UX Design Crash Course Jessica Kreger, Senior Member

You’ve got the words down pat, and are a pro at writing and editing. But when it comes to design, well, that’s a different story. Fear not, as this crash course will illustrate the basics of how to use user interface (UI) design to improve the user experience (UX). We’ll cover user interface terminology, design principles and skills, and improving user interface text. You’ll find links to resources that will give you the foundation that you need to talk to and work with UI/UX designers.

Learning User Interface Applying Design Principles and Terminology Skills When producing documentation, technical commu- As technical communicators, we know that the most nications must describe the user interface elements effective documentation encompasses more than in our products that our customers need. You can just words. We can use visual-verbal communica- learn the UI/UX terminology required to support tion to improve both our product design and our your customers, and meet designers on their turf, by documentation. Because our brain recognizes pat- familiarizing yourself with key terms and their acro- terns when we read, we can apply the five design nyms. principles of balance, alignment, grouping, consistency, and contrast referenced in Technical A great place to start your learning is the glossary of Communication Today to help our users quickly Usability.gov, a U.S. government site that provides scan and locate the information that they need. information on best practices in user experience. Usability.gov also categorizes user interface ele- Even if we aren’t able to directly design and pro- ments: input controls (checkboxes, radio buttons, gram the user interfaces that we document, as user dropdown lists, list boxes, buttons, toggles, text advocates we can have valuable input into creating fields, and date fields); navigational components an engaging experience for our users. Usability gu- (breadcrumbs, sliders, search fields, pagination, rus Susan Farrell and Jakob Nielsen co-authored a sliders, tags, and icons); informational components book, User Experience Careers: How to Become a (tooltips, icons, progress bars, notifications, mes- UX Pro, and How to Hire One, which includes valu- sage boxes, and modal windows); and containers able advice for developing user experience skills, (accordions). both formally (in the classroom) and informally (outside of school). Beyond defining the field and offer- The UX Planet site, a user experience resource, ing tips to enhance our own skill set, the text also also offers an excellent article, UI/UX Design Glos- provides insight on hiring UX talent. sary. Navigation Elements, by the Tubik Studio. The article includes screenshots presenting the elements in action, including helpful animations high- Improving User Interface Text lighting best practices for mobile application design. It offers guidelines for creating seamless navigation When writing user interface text, technical commu- that enables users to complete their goals, efficient- nicators collaborate with designers, product manag- ly solves their problems, and creates a positive ex- ers, and developers to understand the requirements perience along the way. of the business and best advocate for the user. Re- searching how our products work, benchmarking our tools and text against industry standards, and user testing are integral parts of our process. Tech- nical communicators have a unique opportunity to test out the user interface before it reaches produc-

83 Jessica Kreger

tion, and report bugs and suggest enhancements to Johnson-Sheehan, Richard. Technical developers. Communication Today, 5th Edition (Purdue University), 2015. Microsoft’s Windows Dev Center is an excellent resource for best practices in developing user inter- Progressive Disclosure | Nielsen Norman Group (23 face text. The site recommends that we only include April 2018). details that users need to know to complete their https://www.nngroup.com/articles/progressive- task, and progressively disclose the information in disclosure/. digestible chunks with the most important infor- UI/UX Design Glossary. Navigation Elements. UX mation first. If your users will require more infor- Planet (23 April 2018). https://uxplanet.org/ mation, provide a link to your help system. For ex- ui-ux-design-glossary-navigation-elements- ample, Figure 1 below shows a succinct dialog from b552130711c8. the TradeStation platform that greets the user with User Interface Elements | Usability.gov (23 April our new company branding, style, and tone. 2018). https://www.usability.gov/how-to-and- tools/methods/user-interface-elements.html. User Interface Text | Windows Dev Center (23 April 2018). https://msdn.microsoft.com/en- us/library/windows/desktop/dn742478(v=vs.85). aspx. What is UX Writing? | UX Booth (23 April 2018). http://www.uxbooth.com/articles/what-is- ux-writing/.

Figure 1. This dialog from the TradeStation platform places the action on the interactive control (Contin- Author Contact Information ue as Administrator) and uses a conversational tone Jessica Kreger (Not Now, instead of Cancel). Senior Manager, Client Training and Education When technical communicators apply best practices TradeStation Technologies for UI/UX consistently in our reference materials 8050 SW 10th Street, Suite 2000 and procedures, we aid our users understanding Plantation, FL 33324 and help them complete their tasks more quickly, with enhanced satisfaction. Author Biography Jessica Kreger leads the technical documentation team at TradeStation to publish information that Resources empowers active traders around the world. With nearly 20 years of experience in communications, Farrell, Susan, and Nielsen, Jakob. User she has worked at Dell, the University of Miami, Experience Careers: How to Become a UX Pro, Carnegie Mellon University, and Alcoa. Jessica is and How to Hire One (West Conshohocken, PA: passionate about creating optimal user experiences. Infinity Publishing), 2016. She earned a M.A. in Professional Writing from https://www.nngroup.com/reports/user- Carnegie Mellon and a B.A. in English from Penn experience-careers/. State. She is a Senior Member of the STC, belongs Glossary | Usability.gov (23 April 2018). to the Technical Editing SIG, and is a Certified Pro- https://www.usability.gov/what-and- fessional Technical Communicator. why/glossary/a/index.html.

They’re Coming! Combining Teams and Cultures Larry Kunz, Fellow

Your technical communication future will take place against a backdrop of corporate change. Whether you're a permanent employee or a contractor, the companies where you work will evolve through mergers, acquisitions, and realignments. My company, Extreme Networks, anticipated and handled the upheaval that resulted from three major mergers within a year. Leading a cross-corporate team that successfully integrated three separate DITA content bases into a single system, I experienced the dynamics of combining diverse teams, workflows, and tool sets. With my management team, I also worked to align corporate cultures, preserving the best aspects of each company while being sensitive to employees’ concerns and fears. Our approach emphasized empathetic listening and clear communication.

line or—more commonly—brands, technologies, and Steady Growth for Mergers and patents. Struggling companies align to achieve Acquisitions economies of scale or to align to compete against a larger rival. Companies divest parts of their Mergers, acquisitions, and realignments are nothing businesses to focus on other parts. new, but they’re increasingly common across a range of industries. Statistics from the Institute for Not all mergers work as planned. (For simplicity I’ll Mergers, Acquisitions and Alliances (“Number & use the term mergers to refer to all types of Value of M&A Worldwide”) show a steady growth in consolidations between companies.) Competing both the number of mergers and their total dollar product lines can’t be brought into harmony, causing value. the merged company to stumble in the marketplace. Corporate cultures clash instead of blending. Companies merge for all sorts of reasons. Large companies acquire smaller ones to obtain a product

Figure 1. Mergers and acquisitions worldwide

85 Larry Kunz

Case Study: Integrating People, My Experience Workflows, and Tools My experience bears out the fact that successful While the blending of three organizations mergers don’t happen automatically. I’ve learned encompassed a lot of different elements, this case firsthand that successful mergers require thoughtful study focuses on one of them: combining three planning and deliberate action. existing sets of DITA/XML content onto one content management system (CMS) instance. Acquired: Invaded and Conquered When we began, one group was working in the latest In 2005, in the largest software merger up to that version of SDL Knowledge Center, one group was time, a $3 billion company purchased the $2 billion working in an older version, and the last group was company where I was working at the time. working in a different CMS. Swallowed up might be more apt. My colleagues and Prior to the merger, we evaluated the CMS options I sensed that the new company had no interest in available to us and determined that a new instance how we did our jobs, or in whether we were doing of SDL Knowledge Center would be the best choice our jobs well. (We knew that we were.) for the merged group. We thought that Knowledge The acquiring company simply said that from now on Center could accommodate current and projected we’d use a new set of tools and processes. Training workloads, and we acknowledged that many of our was perfunctory: click this, click that, don’t ask merged staff were already comfortable working in it. questions. We never received an explanation of why the new tools and processes were preferable to the The Working Group: Bringing Everyone old, or even of why the merger had taken place. Together We never felt integrated with the larger company; we We knew that changing to the new CMS would entail never felt like we had a voice in decision making. much more than simply moving the DITA source Instead, my colleagues and I felt as if we were being files. Each team had its own workflows for authoring, invaded and conquered. Seeing our old way of life publishing, and translating content—and all of these being threatened made us fearful and put us into a would need to be integrated. defensive posture. When SDL sells its product to a new customer, it Fear, in my experience, is the biggest single factor in typically creates a working group to design the failed mergers. system’s configuration. We quickly realized that, even though some of our writing teams were already Acquiring: Welcoming New Colleagues working in Knowledge Center, we needed to create a working group like that. Fast forward 11 years. I work at Extreme Networks, a producer of networking equipment with about $1 We carefully set up our group to accommodate all billion (US) in annual revenue. viewpoints, to ensure that all relevant issues were aired, and to ensure that everyone felt they were Extreme made three major acquisitions over a one- being heard. In practice, this meant including both year period starting in October 2016—doubling the technical and management people from all of the company’s size. As if to illustrate the relentless teams that were developing content, as well as from nature of mergers, two of those acquisitions—of SDL, the CMS vendor. It also meant that I was business units from former rivals Avaya and appointed to lead the group—counter to SDL’s usual Brocade—contain elements from about a dozen practice of putting one of their own project managers smaller networking companies that operated during in charge. the decades of the 1990s and 2000s. We put an Extreme Networks employee in charge to The people at Avaya and Brocade might have feared foster a sense of unity among the writing teams and the same things I feared at my old job in 2005. But to reinforce the fact that Extreme, ultimately, bore the things have worked out better for them. To help responsibility for making the project succeed. explain why, here’s the story of how we integrated people, workflows, and tools to blend three teams Each biweekly meeting had the same general into one. agenda:

86 2018 STC Technical Communication Summit Proceedings They’re Coming! Combining Teams and Cultures

• A status update on follow-up items from the group meeting. I reported on the group’s progress in previous meeting. the broader staff meetings as well. • Specific topics for that week. All group members knew what topics would be Defeating Fear through discussed because they received a copy of the agenda a day or so in advance. Communication • A summary of new follow-up items: Knowing that fear can do so much damage after a specifically, what needed to happen or what merger, our managers sought to overcome it by decision needed to be made, the timetable, communicating intentionally, frequently, clearly, and and who was responsible. in both directions. Sharing the vision was only one • A check of the project schedule, with part of that process. Communication also involves particular attention to milestones or events listening to how people react and ensuring that they that were coming up soon. know they’re being heard. Writer and career coach Lisa Quast counsels “Show and Tell”: Understanding Each managers to understand what changes are coming, Other and Sharing Good Ideas who the changes will affect, and what the effects will Soon after the project started, the working group held be. She encourages managers to be as forthright as a special "show and tell" session at which the three possible, to understand the team’s honest questions, writing teams demonstrated authoring and publishing and to look deeper. Do the team’s questions reflect workflows using their current tools. Each presenter resentment? Defensiveness? Bewilderment? A was asked to describe in detail their strategies for feeling of disorientation? versioning, metadata, filtering, and content reuse. The “show and tell” session, held before Communicating with the Group and with requirements were finalized for the new CMS Individuals instance, helped everyone understand what the At Extreme Networks, we recognized that while groups had in common and what differences would some people see change as an exciting opportunity, need to be accommodated in the final others have a hard time handling it. Our implementation. We came out of the “show and tell” management team invited feedback, both in group session with a fairly detailed blueprint for defining settings and one-on-one meetings, about what could requirements for the new system. be done to make team members feel more The “show and tell” session succeeded in another comfortable about the changes they were way. It established the new group as a single writing experiencing. team, rather than a collection of three teams. As the We also understood that it’s unwise to force change demonstrations proceeded, we heard comments like too quickly. You won’t get it all done at once, so play “have you tried such-and-such” and “I like how you the long game. Create a sense of shared purpose by did that.”. A spirit of openness and cooperation took establishing common goals. Then prioritize— hold, so that two weeks later, when we met with identifying what needs to change right away and SDL’s representatives to defined detailed what can wait. requirements, each individual saw him- or herself as a member of a single team. Everyone spoke with the Taking a measured approach balances the need to same voice. change with people’s ability to handle change. As much as you can, keep the team clued in to what's coming next—even if sometimes that means saying Guided by Our Vision “I don’t know yet.” It’s better to give the team your Throughout the project, we started with the end in best guess than to leave them in the dark, wary of mind—in other words, we had a vision—and we surprises lurking around the corner. showed everyone the plan for getting there. The vision—one new CMS instance, with all groups Communicating New Processes sharing workflows for authoring, publishing, and The CMS project finished at the end of 2017. But translating—guided the working group. After more work remains before everyone feels like a full articulating the vision at the beginning of the project, member of the blended team. As I write this paper, I kept the working group members focused on it by the last few authors are moving onto Knowledge reviewing the project schedule at the end of every Center and being trained in its use. 2018 STC Technical Communication Summit Proceedings 87 Larry Kunz

We’re developing written processes for activities that, • Respecting every team member’s right to when we had separate, smaller groups, everyone know would understand innately. We can’t assume that • Involving all stakeholders in decisions people from varying backgrounds will instinctively about tools and workflows know how to do things the right way. They have to be • Fostering unity and open communication told what the right way is. • Establishing a sense of shared purpose by Finally, we’re training all staff members in the new defining common goals tools and workflow, with specialized training for those who are using Knowledge Center for the first time. Even though they were kept informed when the CMS Resources was selected and when the working group was Alda, Alan. If I Understood You, Would I Have this carrying out the tool’s implementation, many of them Look on My Face? (New York, NY: Random are still reluctant to give up their old ways of doing House), 2017. things. The training is tailored for people who were proficient with the old tools and workflows— Davey, Liane. “Can Conflict Be Nice?” 3coze blog (3 acknowledging their resistance to change and fear of December 2017). failure and equipping them to overcome them. http://www.3coze.com/2017/12/03/can-conflict- be-nice/. Kanter, Rosabeth Moss. “Ten Reasons People Communicating Every Day Using a Wiki Resist Change.” Harvard Business Review (25 Finally, to increase the sense of inclusion and unity, Sep 2012). https://hbr.org/2012/09/ten-reasons- we’ve launched a Confluence-based wiki site called people-resist-chang. extremedocs, open to everyone in the merged Tanner, Robert. “Organizational Change: 8 Reasons Information Development organization. The wiki Why People Resist Change.” Management Is a contains: Journey blog (13 October 2017, updated 2 April 2018). • An organizational chart and descriptions of https://managementisajourney.com/ people’s roles organizationa l-change-8-reasons-why-people- • Links to policies and procedures resist-change/. • Templates, best practices, and troubleshooting tips for our authoring tools References • Technical and planning information about “Number & Value of M&A Worldwide.” Institute for projects the team is working on Mergers, Acquisitions and Alliances. https://imaa- • A blog area for sharing personal news and institute.org/mergers-and-acquisitions-statistics/. (work-related) opinions Quast, Lisa. “Overcome The 5 Main Reasons People Resist Change.” Forbes (26 Nov 2012). The wiki provides a platform for defining and https://www.forbes.com/sites/ reinforcing a culture of shared purpose and lisaquast/2012/11/2 6/overcome-the-5-main- inclusion—and for having a little fun. You can share reasons-people-resist-change/. tips, find information, ask questions, and share your experience. Participation has grown gradually but steadily: it’s common at staff meetings to hear “You’ll Author Contact Information find that on the wiki.” We think the wiki, at a cost of less than $5,000 per year, is a good investment. Larry Kunz Lead Technical Writer Extreme Networks Ingredients of a Successful Merger 2121 RDU Center Drive, Suite 300 As typified by our experience with the CMS work Morrisville, NC 27560 group, we’ve been pleased with the success we’ve 919 595 4954 had in blending three teams into one. Our experience has reinforced for us that, to be successful, mergers have to be handled through: • Frequent, intentional communication • Active, empathetic listening

All I Know About Collaboration I Learned from Rock & Roll Aiessa Moyna, Associate Fellow

Technical communicators at all levels and in all settings need to work collaboratively. Whether you’re relatively new in your career or a seasoned professional, working as a lone writer/editor or leading a large department, you frequently will have to work on a cross-functional team where your success—and the success of your business—depends on collaborating with colleagues with varying backgrounds, skills and levels of expertise. What can technical communicators learn about collaboration from U2, The Beatles or Nirvana? A lot! We’ll examine the song lyrics and stories of popular rock bands to learn how successful collaborators seek diverse perspectives, build trust, bust barriers, work their networks, manage conflict and, when their best-laid plans go astray, improvise.

Working alone, few technical communicators are in environment, where diversity has been demon- a position to drive the business objectives of the or- strated to drive innovation and employee engage- ganizations they support. To achieve success, they ment, as well as financial results. instead must work as members of cross-functional This can be a challenge, however, for small organi- teams, collaborating with technical SMEs, support zations and small teams within larger companies. staff, leaders, customers, fellow communicators and What if you are a documentation team of one? The others. Teams that collaborate poorly can be slow, first album by Foo Fighters was written, recorded expensive, inefficient, wasteful and prone to mis- and produced by Dave Grohl (the former drummer takes, which can lead to missed deadlines, disap- of Nirvana), who enlisted a co-producer and one pointed customers and brand damage. Conversely, guest guitarist in the creative process (Foo Fighters, teams that collaborate effectively can drive im- 1995). You can produce a great piece of work your- proved speed-to-market, efficiency, productivity, self, but you could work faster, more creatively and quality and customer satisfaction. more accurately—and you would be less prone to Over the course of my career, I’ve experienced both burning out—if you shared the work as part of a bad and good collaboration. I’ve also looked to team. As a lone writer or member of a small team, other teams and alternate professional settings for you may not be able to rely on additional team inspiration and examples, both positive and nega- members on a permanent basis, but you often can tive. Rock bands share several characteristics with bring extended team members (with skill sets differ- work teams in a business setting—they are made ent than your own) into the process for short periods up of individual members with specific skills, devel- of time to assist with specific tasks. oped through years of practice, who perform together to achieve shared objectives. We can learn from their example about collaboration. Here are Lesson 2: Build Trust and Bust Bar- five lessons I’ve learned from rocks bands and mu- riers sicians. “There is no them. There’s only us,” proclaims U2 in “Invisible” (Bono, 2014). Have you ever worked as a Lesson 1: Seek Diverse Perspec- member of a team whose members had competing tives objectives? It is hard to work together when everyone has a different end game in mind, so it is im- “Don’t surround yourself with yourself,” says the portant for teams to align on common objectives band Yes in their song “I’ve Seen All Good People” early in the collaborative process. (Anderson, 1971). This is good advice for technical The diverse perspectives that can help teams col- communicators who work in a collaborative laborate more effectively also can introduce multiple

89 Aiessa Moyna

motivations and agendas into the equation. Yoko and perform together today (with the surviving Ono sometimes is credited with single-handedly members of the original lineup and some special breaking up the Beatles, but it’s more likely that they guest artists) (Eagles, 1994). dissolved because they no longer could agree on All teams experience conflict, and managing it effec- such fundamentals as creative direction and voice, tively is critical to success. Some approaches are and whether to perform live or play solely in the re- more painful than others, but the key is to under- cording studio (Gilmore, 2009). I’ve worked on stand what is at the root of the conflict, have an teams where some members were focused on get- honest (and likely difficult) conversation about it, ting the product out the door by a specific date and and come to consensus on how to resolve it. This then fixing bugs and adding features later, while almost always requires managing volatile emotions, others were focused on developing a fully featured, both your own and those of your collaborators, and high-quality product with no specific release date in it may help to bring in an impartial party to mediate mind. Collaboration suffers when a team’s members the conflict. Van Halen has stood the test of time, have competing interests because they prioritize dif- although with a revolving door of lead singers, two ferently and have a different sense of urgency. A of whom have left and returned to the band twice. In team can work with multiple objectives in mind, alt- the end, the best course of action may be to part hough it’s important to agree on them up front—and ways. In a business setting, this may mean drop- this may require some compromise. ping, dismissing and/or replacing one or more members of the team. Lesson 3: Work Your Network Foo Fighters has come a long way from its first al- Lesson 5: When All Else Fails, Im- bum, which basically was the work of one person. provise The band’s latest album features a lineup of six permanent members, with contributions from Shawn “Plan the work, and work the plan,” goes the old ad- Stockman (of the R&B group Boyz II Men), jazz sax- age. But when appropriate, it’s all right to impro- ophonist Dave Koz, pop star Justin Timberlake and vise—the results may far exceed your expectations. music legend (and former Beatle) Paul McCartney Each year, the Rock & Roll Hall of Fame inducts the (Foo Fighters, 2017). members of the incoming class by staging musical tributes to celebrate the performers, non-performers As a technical communicator, you may be a lone and early influences being honored. The musicians voice, even as a member of a diverse team. When assembled for each tribute often represent a variety you need some backup, don’t hesitate to reach be- of backgrounds, musical styles and even genera- yond your own organization. You have a great net- tions; they may or may not have played together be- work in STC; use it to bounce ideas off peers who fore; and their rehearsal time may have been lim- work in similar positions for other companies and in ited. As a result, while the tributes begin with a set other industries. Stay in touch with former col- list, they sometimes end up becoming extended jam leagues who have moved on to other roles and or- sessions—which works when you assemble tal- ganizations. Connect with other technical communi- ented musicians who know their craft, can easily cators on social media or at local Meetups and user adapt to new situations, plus are willing to set aside groups. Borrow their best practices, and learn from their own plans and follow someone else’s lead their mistakes. And when you need another voice or when inspiration strikes (Rock & Roll). an extra pair of hands to help strategize, plan and do the work—and the budget allows for it—consider For collaborative teams, improvisation generally hiring someone to help you, either full-time or on a comes into play in two situations: when someone part-time or temporary basis. sees a better way forward than originally planned, and when it becomes clear that the plan isn’t working as originally intended. Both require the team Lesson 4: Manage Conflict members to collectively and individually display flexibility, humility, inquisitiveness and a keen sense of “When Hell freezes over,” replied Don Henley when self-awareness. The team also must remain fo- asked whether the Eagles would ever play together cused on achieving their shared objectives, rather again following their breakup in 1980. Fourteen years later, the band reunited for the “Hell Freezes than achieving their plan as an end in itself. Re- maining focused on the needs of the customers and Over” album and tour, and they continue to record business will help ensure the team’s willingness and

90 2018 STC Technical Communication Summit Proceedings All I Know About Collaboration I Learned from Rock & Roll ability to respond when new opportunities present Eagles. Hell Freezes Over (Geffen), 1994. themselves, enabling them to take action more Foo Fighters. Concrete and Gold (RCA/Roswell), quickly and readily, rather than continuing to pursue 2017. actions that will not work or will not work as well as Foo Fighters. Foo Fighters (Capitol/Roswell), 1995. an alternative. Gilmore, Mikal. "Why the Beatles Broke Up." Rolling Stone (3 September 2009). Conclusion https://www.rollingstone.com/music/news/why- the-beatles-broke-up-20090903. Teams that work collaboratively generally work Rock & Roll Hall of Fame (Cleveland, OH). more successfully. By following the five lessons https://www.rockhall.com. above, technical communicators working in teams can achieve more collectively than they can individually, which is good for customers and good for Author Contact Information business. Aiessa Moyna Public Affairs Director American Express Resources 200 Vesey Street, MC 01-48-05 New York, NY 10285 Campbell, Anita. “5 Benefits of Collaboration in Your +1 212.640.2020 Small Business.” Small Business Trends (16 [email protected] January 2017). https://smallbiztrends.com/2017/01/benefits-of- collaboration-small-business.html. Author Biography Gallo, Amy. HBR Guide to Dealing with Conflict A veteran technical communicator, Aiessa Moyna (Boston, MA: Harvard Business Review Press), has been a collaborator on numerous teams in a va- 2017. riety of corporate, nonprofit and government set- Johnson, Stefanie K. “What 11 CEOs Have Learned tings. She currently works as a public affairs director About Championing Diversity.” Harvard at American Express, providing communication con- Business Review (17 August 2017). sultation and support for the CIO and the Technol- https://hbr.org/2017/08/what-11-ceos-have- ogy division. Previously, she was responsible for learned-about-championing-diversity communication strategy and tactics for information Morgan, Jacob. “The 12 Habits of Highly security and infrastructure operations projects. Collaborative Organizations.” Forbes (30 July Aiessa began her career as a technical writer and 2013). editor, and later managed employee communica- https://www.forbes.com/sites/ tions for a scientific and technical company. She jacobmorgan/2013 /07/30/the-12-habits-of- holds a B.S. in technical communication from New highly-collaborative-organizations/ Mexico Tech and an M.A. in communication studies #31f5a8bb3683. from the University of Nevada, Las Vegas. Nixon, Natalie. “5 Reasons Why Collaboration Is Aiessa is a long-time STC volunteer, having served Essential in Today’s Business Environment.” the STC New York Metro, Phoenix, Southern Ne- Inc. (15 August 2014). vada and New Mexico Tech Chapters. A former So- https://www.inc.com/natalie-nixon/5-reasons- ciety treasurer and member of the board of direc- why-collaboration-is-essential-in-today-s- tors, she is an Associate Fellow, member of the business-environment.html. Sigma Tau Chi student honor society and winner of the Distinguished Chapter Service Award. She has References served as a judge for STC competitions at the international, regional and community level. She cur- Anderson, Jon, and Chris Squire. “I've Seen All rently is a member of the Associate Fellows Com- Good People.” The Yes Album (Atlantic), 1971. mittee and chairs the Elections Committee for the Bono. "Invisible." Songs of Innocence (Island), New York Metro Chapter. 2014.

From Open Source Volunteer to Full-Time Tech Writer Gale Naylor

"Find an open source project and start contributing" is hands-down the best career advice I ever received. In this paper, I'll briefly describe what open source software is, and talk about how I used my volunteer experience on the Apache Taverna project to become a technical writer at Facebook. I'll describe the tangible and intangible skills I gained, as well as how I got noticed when the primary communication channel was a mailing list, and no one knew who I was.

version is ready for release and what future Disclaimer direction the project should take. However, I’m not an open source expert, and this paper de- you can make substantial contributions with- scribes my personal experience with open source out becoming a committer. and how it helped me get a job at Facebook. Note: • Communication. How projects communi- There are many ways to get a job at Facebook. cate may depend on the project and the group it belongs to, but when I started working on the Apache Taverna project, the mail- What Are Open Source Projects? ing list was the only communication chan- Unlike commercial software companies, no one nel. Even now, all formal communication owns the software created by open source projects, (votes and critical discussions) is required to and the software is licensed, not sold. Most im- happen on the mailing list. However, with portantly, open source projects are “open,” meaning the advent of chat apps, some of Taverna’s that anyone can contribute, modify the code, or informal communication has moved onto even make a copy and change it. (This is called Gitter. “forking.”) Contributors first sign a Contributor Li- • Contributions. Many projects, including cense Agreement (CLA). Contributions include any- Apache Taverna, use GitHub for contribu- thing the project needs, including documentation, tions to code and readme documentation. In website development, research, as well as coding Taverna’s case, most of their documentation and testing. In some projects, all the contributors is on the website, which is updated using are volunteers. Large companies, such as Google the Apache CMS (content management sys- and Facebook, often have open source projects that tem). include employees as well as volunteer contributors • Typical issues. Some concerns faced by and committers. open source projects are licensing and at- Here’s what I learned from my experience with one tracting and retaining contributors. Licensing project: is what lets anyone use the software, but there are many licenses with different rules. • Communities. In my experience with the Because software applications typically use Apache Software Foundation (ASF), open existing software to handle common func- source projects are communities, with differ- tions, reviewing the pedigree for all the li- ent guidelines and cultures. Anyone who braries and utilities (called, dependencies) contributes is called a “contributor,” but pro- used in a project can be a big task. jects also have voting members who are called “committers.” In the ASF, project There are many open source communities. In addi- members nominate and vote to bring new tion to the Apache Software Foundation, communi- contributors into the project. Members also ties include the Linux Foundation and GitHub. There vote on decisions, such as whether a are also specialized communities like the Open Source Robotics Foundation. Commercial software

92 From Open Source Volunteer to Full-Time Tech Writer

Figure 1. A list of some of the top open source projects from 2017 companies can have open source presences as well, such as Facebook Open Source and Google How Did I Get Started? Open Source. Figure 1 shows a snapshot of some I wasn’t aware of the breadth of open source proof the top open source communities from 2017, jects and communities, so I began searching for along with related commercial companies. projects in the one place I had heard of: The Apache Software Foundation. I thought a new pro- What Did I Gain from My Experi- ject would be easier, so I looked at their list of “Incu- bator” projects and found one that looked interest- ence? ing. I signed up for the mailing list and started moni- I expected to gain tangible benefits from working on toring their communications. an open source project. I knew I would create rele- Of course, nothing made sense at first. (And, it vant and current work samples and practice skills turned out that while Taverna was on the incubator (such as Markdown and Git) in an authentic envi- list, it was a mature project, with a substantial leg- ronment. I was pleased to find out that I also gained acy, that had recently decided to go open source.) I experience using tools I did not otherwise have ac- worked offline to understand the project, which lets cess to, such as the Apache CMS, JIRA, and Con- scientists create and share in situ digital experi- fluence. ments. But I continued to monitor the mailing list, What I did not appreciate, was the extent that I and eventually began to recognize people, their would become familiar with open source language roles, and some of the terminology. and issues. In addition to learning why licensing is Because I was also changing careers, I researched always a concern, I learned how a project vote is technical writing and how to work with developers. I handled (+1 to agree) and how one project builds, discovered a resource that described how to “ask tests, and releases software. I also learned (a little questions the smart way,” (Raymond) which came bit) about how to work with an SME (subject matter in handy as I attempted to get noticed. expert). Now that I had a project, and things were starting to I was even more pleased to discover the intangible make sense, I looked for ways to help. Confusion results from my open source work: credibility and and new contributors were the two keys. confidence. I gained an understanding of language and processes that an employer found useful and learned that I could make meaningful contributions that were appreciated.

2018 STC Technical Communication Summit Proceedings 93 Gale Naylor

How Did I Get Noticed? class for Android programming when Face- book hired me. Confusion about which modules were deprecated • Write. I wrote all the time. I created portfolio (outdated) lead to my first contribution. I created a samples and wrote several blog posts. diagram of the Taverna Modules, color-coded to show which were experimental or deprecated. I Every single one of these activities was instrumen- happily sent my diagram to the mailing list and tal. waited for a response. Nothing happened. Summary It turned out the mailing list stripped out attach- Here is what worked for me. YMMV (Your Mileage ments. I’m not sure why no one responded to point May Vary). out the missing file, but it’s likely because they were all volunteers with full-time jobs and did not yet • #1 Lurk on the mailing list. Each project know who I was. has its personality and culture. Learn about the people as well as the technical details of What worked for me was to create a Word- the project. Who are the main contributors? Press.com blog post and include a link to the post in What roles do they play? What types of my message. The main contributor was ecstatic questions do users ask? Are there new about the diagram and asked if he could include it in members who are asking questions? Is their documentation. (Yes!) After that, I stayed ac- there a place for you? tive on the mailing list, asked questions and sug- • #2 Find a way to contribute. With luck, gested areas where I could help. One of the first your lurking has paid off, and you can see a things I did was update and reformat their record of need you can fulfill. One thing that worked academic publications. for me was to help a student contributor with I was lucky Taverna had a Google Summer of Code his documentation. New people can be a (GSoC) student that year. As he learned about Ta- source of information (when they ask ques- verna, I also learned and helped him with his docu- tions), and helping them is another way for mentation. It turned out that the Taverna project ap- you to contribute. preciated active participation and mentorship: In just • #3 Figure out how to get noticed. It’s easi- a few months, they asked me to become an Apache est if you have a contribution that relates to committer. a topic the community is currently discuss- I started maintaining the website, and when Ta- ing. Look for opportunities where a new con- verna prepared its first Apache release, I created tributor was confused, and document the re- two detailed release procedures: one main proce- sulting explanation. When you post, offer dure and a supplement for newbies like me. I real- your contribution as a suggestion and ask ized it was much easier it is to contribute when big for confirmation and feedback. (Be humble.) things were happening. If you have an attachment, make sure the mailing list doesn’t strip it out. I used a WordPress blog to post contributions and in- What Else Did I Do? cluded a link to the post in my mailing list message. Because I was changing careers, I had lots of homework to do: • #4 Become a part of the community. Reg- ularly monitor the mailing list and participate • Make Connections. I joined and became in discussions where you can. Ask ques- active in my local STC chapter. I also at- tions but do your homework before asking. tended meetups, such as Write the Docs Show them you want to be on the team, and and started meeting people who write devel- the committers will be happy to have you on oper documentation. board! • Learn. I took LOTS of classes. I started with free classes at Code School, then decided to pay for Lynda.com classes, which were very helpful for refreshing my coding skills. I was in the middle of an in-depth Coursera

94 2018 STC Technical Communication Summit Proceedings From Open Source Volunteer to Full-Time Tech Writer

Author Contact Information Resources Gale Naylor “Apache Taverna (incubating).” Apache Taverna (4 Documentation Engineer March 2018). Facebook https://taverna.incubator.apache.org/. 1 Hacker Way Menlo Park, CA 94025 Belk, William. “Top 6 Open Source Projects 650.509.0722 In 2017.” Hackernoon (16 July 2017). https://hackernoon.com/top-6-open-source- projects-in-2017-db34b9d034a2. Author Biography Code School. https://www.codeschool.com. I was an aerospace engineer for 15 years, then Coursera. https://www.coursera.org/. taught myself Visual Basic and became a program- “Finding Open Source Projects on GitHub.“ GitHub. mer/analyst. In June 2015, I started contributing to https://help.github.com/articles/finding-open- the Apache Taverna project. My contributions in- source-projects-on-github/. clude creating a release procedure and updates to galenaylor. https://galenaylor.wordpress.com/. (My the website. In December of 2015, I was invited to Apache Taverna posts.) become an Apache Taverna committer. “Great for New Contributors.” GitHub. I started at Facebook in October 2016 as a contract https://github.com/showcases/great-for-new- Technical Writer and converted to a full-time em- contributors. ployee position in March of 2017. I also have a mas- ”How to Contribute to Open Source.” Open Source ter’s degree in Education and like to design outdoor Guides. living spaces. I’m active in my local STC chapter https://opensource.guide/how-to-contribute/. and am currently Chapter President. Lynda.com. https://www.lynda.com/. “Meetups.” Write the Docs. http://www.writethedocs.org/meetups/. Society for Technical Communication. www.stc.org. Software Carpentry. https://software-carpentry.org/. (I did not try this one.) Thakker, Dharmesh, Schireson, Max, and Nguyen- Huu, Dan. “Tracking the Explosive Growth of Open-source Software.“ TechCrunch.com (7 April 7 2017). https://techcrunch.com/2017/04/07/tracking-the- explosive-growth-of-open-source-software/. (Source for 2017 Battery Open Source Software Index.) Weber, Jen. “Your First Open Source Contribution: A Step-by-step Technical Guide.” Medium.com (11 December 2017). https://medium.com/@jenweber/your-first-opensource-contribution-a-step-by-step-technical- guide-d3aca55cc5a6. “Welcome! Let’s Do Some Open Source!” First Timers Only. https://www.firsttimersonly.com/.

References Raymond, Eric S. “How to Ask Questions the Smart Way: Introduction.” catb.org. http://catb.org/~esr/faqs/smart- questions.html#intro.

Creating and Training Your Own AI Instance Using DITA Vishal George Palliyathu

The rise of Artificial Intelligence (AI) is imminent. AI is pervasive across industries and disciplines; even in the discipline of Technical Communication. But is this cause of worry, or rather, is it an opportunity? If AI makes sense of intelligent and structured content to perform tasks that were once performed by humans, how can we, as Technical Communicators and Information Designers better design and curate information to create new corpus of information just for AI. How can a Technical Communicator build an Artificial Intelligence bot to respond and chat for product related help?

Some of the AI products that we come across Consider the scenario in 2020, when the world are closed boxes—they offer you little infor- would be connected by 2 billion zero touch de- mation into how they work and how they pro- vices, 7 billion personal devices, 1.3 billion cess the information for you. wearables, and 5.7 billion IoT endpoints. That would be an increasingly connected and a con- But then there are some AI offerings that help verged world as well. The majority of devices you create your own bots from scratch. They of- will be designed to function with minimal or zero fer you an open kitchen where you can play touch. Using contextual information will become around with the ingredients and come up with a crucial factor in user acceptance. Most of us your own recipe. They might not be production are going to emit a lot of rich context with our ready, but they offer you a glimpse on how the GPS, search queries, app usage, and digital AI does its thinking and what you need to help it foot prints. It might be perhaps safe to say that get accurate. This paper lists the shifting land- even before you ask a query, the bot would scape of technical publication, the opportunities, have synthesized your location and context, and bots—their type and evolution, and how you can would already have a primed answer ready for set up and train your own bot using your DITA you. files. Annette Zimmermann, the Research Director at Gartner, has predicted that “AI, machine learn- The Changing Technological ing and VPAs will be the major strategic battle- Landscape grounds from 2017, and make many mobile apps fade and become subservient of VPAs.” The day that we interact more with a Virtual Per- This is a very good reason why we should now sonal Assistant (VPA) than with apps on our move away from a publishing-model of docs to connected devices is not far away. conversational-model. This is also a very good Gartner predicts that 20 percent of all user inter- reason why we should have a relook at our con- actions with the smartphone will take place via tent strategy. We need to accommodate the ris- virtual personal assistants by 2019 (Gartner, ing need for the future – not just cater to the 2016). Forrester predicts that by 2025, 14.4 mil- publishing needs of humans, but for enabling lion US workers will wear smart glasses (that our structured and semantically enriched docs might deliver VR-enabled micro-content to be to be consumed by bots. delivered) (Forrester, 2016).

96 Creating and Training Your Own AI Instance Using DITA

Search vs Bots method employed in tokenizing the query, identifying the constituents, testing the hypothesis One of the most common questions from Infor- and then generating the answer. mation Developers is, “How is a bot different from a search?”. Well, a search gives you multiple answers, and the onus of finding the right Types of Bots answer rests upon you. Whereas, a Bot gives There are three basic types of bots, and these you a single answer, with a certain confidence are classified based on the logic that is used to level. retrieve an answer. While a search works on the basis of indexing and the metadata that is available with them, Rule-based Bots most advanced bots can generate a hypothesis, subject the hypothesis against a number of The Rule-based bot can answer questions probable outcomes and then generate an an- based on predefined rules on which it is trained. swer with a confidence level. It needs to be You can choose to tailor either a simple rule or reckoned that the confidence level is improved a complex rule. Every possible question or sce- over time, and with additional corpus. nario, and their variations need to be foreseen, and answers to each one of them should be Consider the following question, “I have just pur- keyed in. chased the SampleProduct and have completed the installation. I’m trying to configure it with But note that this bot model would be restrained WAS now. How do I go about it?” A search in answering a question where the pattern does might retrieve every single answer to the query, not match with the rules on which the bot is based on all the keywords that it has identified, trained. Artificial Intelligence Markup Language but a bot would break up the query into its con- (AIML) is a language based on XML that lets stituent intents and entities, and would evaluate developers write rules for the bot to follow. A the answer. The following method outlines the major setback here is that rules for different scenarios is very time consuming and it is impossible to write rules for every possible scenario.

Figure 1. A bot search result

2018 STC Technical Communication Summit Proceedings 97 Vishal George Palliyathu

The bots can handle simple queries but fail to particular intent. An entity defines a class of ob- manage complex queries (Shridhar, 2017). jects, with specific values representing possible objects in that class. Retrieval Model-based Bots Dialog. The dialog uses the intents and entities that are identified in the user's input, plus con- This model is a much-evolved version, com- text from the application, to interact with the pared to the rule-based models. The Retrieval user and ultimately provide a useful response. model-based bots are trained on a set of ques- Consider the following examples: tions, their variations and its possible results. In other words, they do not answer from a pre-de- • Switch on the headlamps. fined set of answers. These bots can generate • Turn on the radio. their own answers and can deliver unique an- • How can install Liberty? swers. But this is often at a great cost – they are more prone to errors, when the syntax of the • How do I configure a Workload Man- language comes into the picture. However, this ager? drawback can be rectified if the bot is trained • How do I resolve Error 56623? extensively. • How do I troubleshoot installation issues? Generative Model-based Bots Red = Intents. Blue = Entities. This is the most advanced model prevailing in the industry today. The bot is trained to decon- Training Your Bot Using DITA struct, tokenize and then identify parts of a Files query and then generate various hypothesis to test the query and find answers to the query. Technical communicators can leverage DITA, The complexity can range from simple rules for due to its following characteristics: a query to complex rules using some machine • DITA is based on XML. learning algorithm to find the most appropriate answer. Also, there is no issue with the lan- • It has inherent semantics. guage and grammar as the answers are pre-de- • It is rich in syntax, conditions, and filters. termined and it cannot go wrong in syntax man- • It is a developer-friendly source. ner. Examples are Google Smart Reply and IBM • It can use scripts to migrate. Watson. • It features modularity. However, it needs to be kept in mind that there • It offers reusability. are hybrid model bots as well. A rule-based model can always be improved upon to include The key advantage of using DITA as a source the capabilities of a retrieval model-based bot. input for training the bot on identifying the in- Bot capabilities are continuously worked and tents and entities is that DITA is already seman- enhanced upon and it is common to find hybrid tically enriched. Simple scripts can map the in- models across the industry. tents to the User goals or Gerunds, while the entities can be mapped to the product related nouns. Content form the body element can be Setting Up Your Own Bot mapped into a dialog answer. The AI schema Prerequisites. A set of DITA files and DIT- can thus be visually represented as in Figure 2. AMAP files, and an IBM Cloud account. Based on the queries that are asked, the intents Intent. A purpose or goal expressed as a cus- and entities can get activated, and the dialogs tomer input to a chatbot. that are associated with them are retrieved. Note that variations of the same questions can Entity. A term or object in a user's input that thus be understood by the bot (Figure 3). provides clarification or specific context for a

98 2018 STC Technical Communication Summit Proceedings Creating and Training Your Own AI Instance Using DITA

Figure 2. Visual representation of an AI schema

Figure 3. Dialogs understood by a bot

2018 STC Technical Communication Summit Proceedings 99 Vishal George Palliyathu

Figure 4. Intents

Content Strategy for References Leveraging DITA Content to Be Forrester. “How Enterprise Smart Glasses Will Bot-consumable Drive Workforce Enablement.” Forrester (21 The content strategy needs to be evolved over April 2016). time, with periodic evaluation and updating. It is https://www.forrester.com/report/How+Enter ideal to stay as close to the DITA conventions, prise+Smart+Glasses+Will+Drive and ensure that the content type is appropriate +Workforc e+Enablement/-/E-RES133722. for the specialization that is used. Internal tax- Gartner. “Gartner Says by 2019, 20 Percent of onomies can also be leveraged to make the User Interactions with Smartphones Will content as containable and molecular as possi- Take Place via VPAs.” Gartner Newsroom ble. This would ensure that only the very spe- (21 December 2016). cific information pertaining to the query is picked https://www.gartner.com/newsroom/id/3551 up by the bot (Figure 4). 217. Shridhar, Kumar. “Rule Based Bots vs AI Bots.” Medium (22 May 2017). https://medium.com/botsupply/rule-based- Resources bots-vs-ai-bots-b60cdb786ffa. "Watson Assistant." IBM Cloud Docs (27 April 2018). https://console.bluemix.net/docs/services/co nversation/gettingstarted.html#gettingstarted.

100 2018 STC Technical Communication Summit Proceedings Creating and Training Your Own AI Instance Using DITA

Author Biography Vishal George Palliyathu has around 11 years of Information Development experience, with IBM and Cisco. He has led several migration and revamping efforts with a strong focus on better information design and ease of use using minimalist principles. As a DITA evangelist with four patents and a paper published on the DITA framework, he has also presented at DITA Eu- rope, tcworld, and STC conferences. He has successfully worn many hats over the last 11 years—that of an Editor, Information Developer, Build Smith, Lead, and Information Architect.

PICTURE PERFECT! How to Turn Words and Data into Powerful Graphics Mike Parkinson, Microsoft MVP, CPP APMP Fellow

Learn to turn your words, data, and ideas into clear, compelling graphics. Visuals, when done right, improve understanding, recollection and adoption.

What we see has a profound effect on what we do, hypothesize that this almost universal response how we feel, and who we are. Through experience stems from the years our ancestors spent on the sa- and experimentation, we continually increase our vannas in Africa. (Johnson) understanding of the visual world and how we are People think using pictures. John Berger, media influenced by it. Psychologist Albert Mehrabian theorist, writes in his book Ways of Seeing (Penguin demonstrated that 93% of communication is nonver- Books, 1972), “Seeing comes before words … The bal. (Dr. Mehrabian notes that the actual percentage child looks and recognizes before it can speak.” Dr. varies situationally but nonverbal communication Lynell Burmark, Ph.D. Associate at the Thornburg carries great weight.) (Mehrabian) Studies find that Center for Professional Development and writer of the human brain deciphers image elements simulta- several books and papers on visual literacy, said, neously, while language is decoded in a linear, se- “… unless our words, concepts, ideas are hooked quential manner taking more time to process. Our onto an image, they will go in one ear, sail through minds react differently to visual stimuli. the brain, and go out the other ear. Words are pro- Relatively speaking, in terms of communication, tex- cessed by our short-term memory where we can tual ubiquity is brand new. Thanks to millions of only retain about 7 bits of information (plus or minus years of evolution, we are genetically wired to re- 2). This is why, by the way, that we have 7-digit spond differently to visuals than text. For example, phone numbers. Images, on the other hand, go di- humans have an innate fondness for images of rectly into long-term memory where they are indeli- wide, open landscapes, which evoke an instant bly etched.” Therefore, it is not surprising that it is sense of well-being and contentment. Psychologists much easier to show a circle than describe it (Figure 1).

Figure 1. A graphic vs. textual description for a circle.

102 PICTURE PERFECT! How to Turn Words and Data into Powerful Graphics

When it comes to quick, clear communication, use a can see themselves in your graphic. Connect with combination of the two. Include visuals and brief their world. textual descriptions to increase the likelihood of success. STEP 2: Know Your Message Making graphics is 50% concepting and 50% rendering (Figure 2). Concepting is the discovery pro- Your message is your takeaway. Your message is a cess and rendering refers to the creation of your one-sentence summary of your graphic. I recom- graphic for final distribution. Follow these six steps mend including a benefit followed by how the bene- to develop effective graphics. fit will be achieved. The benefit gives your audience a reason to care about your content. Figure 3 is an example of an appropriately structured message. STEP 1: Know Your Audience Use the message to develop the title of your Know who they are, what they want to see, and why graphic. For example, the title for this visual might they should care. Learn what your audience truly be “3 Steps to Reduce Cost.” Your benefit can be desires. Your target audience is the sole reason explicit or implicit as long as your audience knows why you are creating your visual. Tailor your graphic what they will get after they understand your to your target audience. Make sure your audience graphic.

Figure 2. Make successful visuals using Mike’s visualization and rendering process.

Figure 3. Takeaway structure to help ensure audience engagement.

2018 STC Technical Communication Summit Proceedings 103 Mike Parkinson

a conclusion. You want your content to have a logi- STEP 3: Explain or Prove (Your cal flow that helps your audience understand (and Message) agree with) your message. The final conceptualization step is to explain or prove your message. For example, using the previ- STEP 6: Visualize ous message (“Reduce cost in three steps.”), ex- Finally, use one of the following three visualization plain the three steps and prove how they reduce techniques to augment or replace your text. cost. 1. Literal Method: Literally show that which is being described. STEP 4: Chunk (Your Content) 2. Quantitative Method: Use a quantitative chart when communicating amount, value or Once you have your message and explanatory text, time. chunk the information into small, bite-sized, digestible pieces. To chunk the information, highlight the 3. Substitution Method: Use a visual metaphor, most important elements and delete all other infor- simile or analogy to communicate content mation. The goal is to eliminate words that are un- that is too complex for your target audience. necessary to communicate your message and Figure 4 is an example of steps 4 through 6. (This achieve your goals. example was used for a PowerPoint presentation. Subsequent slides would further explain the three STEP 5: Assemble (Your Chunks) clever keys. In the final version, an alternative approach was used for the final rendered slide to illus- Next, assemble the chunks of information to tell a trate that the keys secure the lock.) story. Your graphic should have a starting point and

Figure 4. Steps 4, 5, and 6 examples.

104 2018 STC Technical Communication Summit Proceedings PICTURE PERFECT! How to Turn Words and Data into Powerful Graphics

TIP: Download a copy of my Graphic Cheat Sheet Author Contact Information (www.BillionDollarGraphics.com/GCS.pdf) to quickly pick the best graphic type to communicate your con- Mike Parkinson tent. Owner Billion Dollar Graphics Follow these six steps to turn your words, data and 7308 Ivycrest Place ideas into powerful graphics that help you achieve Annandale, VA 22003 your goals. Practice. The more you do, the better 703.608.9568 you will be. If you get stuck, contact me at [email protected]. I’m always happy to help. Author Biography Mike Parkinson is 1 of 13 Microsoft PowerPoint MVPs in the U.S. (1 of 36 in the world). He is an internationally recognized visual communication ex- Resources pert, trainer and award-winning author. Mike regu- Parkinson, Mike. Do It Yourself Billion Dollar larly works with and trains at large companies (e.g., Graphics (Annandale, VA: PepperLip), 2006– Microsoft, Lockheed Martin, FedEx), government 2016. agencies (e.g., NSA, CMS) and at international con- Parkinson, Mike. Graphic Cheat Sheet. ferences (e.g., ATD, APMP, IVMG). Mike owns Bil- http://www.billiondollargraphics.com/GCS.pdf. lion Dollar Graphics (www.BillionDollar- Graphics.com) that develops innovative graphic solutions and is a partner at 24 Hour Company References (www.24hrco.com), a premier creative services firm. His Billion Dollar Graphics book and Graphic Cheat Johnson, Steven. “Beauty and the Beastly PC, The Sheet help organizations and agencies achieve Graphics on Your Screen Can Affect the Way their goals using clear, compelling graphics. Contact You Feel—and Think.” Discover 25.5 (May Mike at [email protected] and (703) 2004): 20–21. 608-9568. Mehrabian, Albert. Silent Messages (Belmont, CA: Wadsworth), 1971.

Lessons Learned: What Harry Potter Professors Teach Us About Instructional Design Jamye Sagan, Senior Member

As technical communicators, we can help communicate the future by being ready to tackle any project we receive, including developing training materials and programs—even if we had never studied instructional design.

Education plays a crucial role in the Harry Potter series by J.K. Rowling. At Hogwarts, where Harry and his friends study magic, we witness several examples of instruction in action. Each of these professors—whether terrible or terrific—has important lessons to share with us regarding effective instructional design and training delivery.

Here, we will profile various Hogwarts professors and analyze the effectiveness of their lesson delivery. Within the lens of each professor profile, we will share practical tips on tackling common training development issues, as well as provide some real-life (aka Muggle) training examples. At the end, you will have the necessary basic tools to confidently tackle many basic training requests.

Even if you have neither read the Harry Potter books nor watched the movies, you will still learn something from the Hogwarts professors.

Technical communication and instructional design how it’s done. Then she has the class get into small share much in common. The Society for Technical groups and practice doing it themselves (Chamber Communication defines technical communication as of Secrets, pp. 91-94). “any form of communication that exhibits one or more of the following characteristics: communi- Lesson Analysis cating about technical or specialized topics, communicating by using technology, and providing in- Sprout’s lesson is thoroughly well-constructed. First, structions about how to do something”. Instructional she states the lesson objective at the beginning of design—“the entire process of analysis of learning class –repotting mandrakes. She also encourages needs and goals and the development of a delivery class participation by asking several guiding ques- system to meet those needs”—incorporates all as- tions. For instance, she begins by asking what the pects of technical communication, especially the properties of mandrakes are. Then she asks why last point about providing instructions. Let’s peek mandrakes are dangerous. This discussion then into the classrooms of some of the Hogwarts pro- segues into stating that mandrakes are used to de- fessors from Harry Potter to see what we can learn velop antidotes, thus the reason why they are culti- about how to best provide instruction to our learn- vated. Next, Sprout gives clear instructions for her ers. class activity, even warning the students to wear protective earmuffs since the mandrake’s cry can cause pain or death, She alerts the class when to Sprout: Repotting the Essentials put on their earmuffs, and when it is safe to remove In the greenhouses outside the castle, Herbology them. Finally, after demonstrating the activity her- professor Sprout teaches her students how to repot self, she directs the students through the exercise. mandrake plants. She begins by showing the class

106 Lessons Learned: What Harry Potter Professors Teach Us About Instructional Design

Lesson Takeaways ty. Once she announces the activity (reading tea leaves), she tells the students exactly what they Identify what your learners need to know. • need to do –sin in pairs, retrieve teacup with tea, Once you have done so, then begin writing drink tea until dregs remain, swirl cup three times learning objectives. Learning objectives are with left hand, turn cup upside down onto saucer, simply what you want your learners to know. wait for tea to drain, and finally give cup to partner, Make sure these objectives are specific, who will then interpret the results based on the measurable and tangible—that they can be symbols in the textbook. Trelawney’s lesson is a seen, felt, or heard. When defining learning good blend of guided and individual practice, since objectives, refer to Bloom’s Taxonomy for she has them use their textbooks to interpret the tea examples of measurable verbs to use, de- leaf shapes, yet walks about the classroom to ob- pending on whether you want your learners serve and provide guidance as needed. to use a glucometer to measure blood sug- ar, or troubleshoot issues with a drug dispensing machine. Once you have defined Lesson Takeaways your learning objectives, make sure your ac- These lesson takeaways apply to in-person training tivities support them. where you can easily observe your students. • Differentiate between “need to know” and “nice to know”. When developing • Explain procedures before beginning the training materials, keep things simple. Cover activity. Make sure your learners know only what your learners need to know. If the what they need to do before they begin. information is “nice to know” vs. “need to • Walk around the classroom. Observe and know”, cut it from the training. You can al- offer help as needed. How would you do ways provide this optional information as this? use guiding questions to help students reference material elsewhere. Having clear- arrive at the right answer—don’t just give cut goals and objectives will help you keep away the answer. For example, if you’re the training on track since you have already teaching someone how to give a blood defined what you want your learners to pressure reading and they applied the cuff know. upside down, note mentally what is incorrect • Create assessment checklists. Such and ask the student about that incorrect checklists help you determine how well your item. learners are grasping the topic at hand. When designing assessment checklists, de- Snape: Howling Relevant Lesson on termine the overall step(s). Then break those steps down into easy-to-follow com- Werewolves ponents, list of actions, or list of concrete When the Professor Lupin, the regular Defense characteristics. These checklists are also Against the Dark Arts teacher, is out ill, Snape takes useful for learners, to self-evaluate their own over the class as a substitute teacher and teaches performance, thus fostering practice beyond the class about werewolves. After his lecture, the classroom/training setting. Snape assigns homework—write a paper identifying the characteristics of werewolves. Professor Lupin Trelawney: Predictions of Success is a werewolf; Lupin and Snape were enemies while in school together. Snape’s lesson was his way of with Activity Explanation revealing Lupin’s true identity without blatantly say- In her tower classroom, Divination professor ing so (Prisoner of Azkaban, pp.132-139). Trelawney leads her students through the process of preparing and interpreting tea leaves in predicting Lesson Analysis the future (Prisoner of Azkaban, pp. 104-108). Despite the devious nature of the lesson, Snape’s lesson clearly demonstrates the necessity to make Lesson Analysis sure lessons and their content are relevant and cur- Like Sprout, Trelawney presents clear learning ob- rent. jectives and easy-to-follow steps for the class activi-

2018 STC Technical Communication Summit Proceedings 107 Jamye Sagan

Lesson Takeaway task at hand? What is their work environment like? How do you envision them using Make sure your instructional materials • your materials—via mobile device? Printed contain relevant info. Training content cheat sheet? Ask yourself these basic ques- should reflect current procedures or infor- tions to give yourself focus when designing mation. For instance, if you are developing the materials. training for a software application, be sure to use the same software version that most of • Don’t focus only on the theory. While it is your end users will be using. However, if good to have some background knowledge tools/version will look different, but function of something, there is no good substitute for is the same, make sure you add a statement hands-on experience. We will provide ex- stating as such, to minimize any confusion amples of hands-on activities later in this with the change in cosmetic appearance. presentation. • Give learners a chance to practice their skills in a risk-free environment. Exam- Umbridge: Wand-Free “Practice” ples include pre-developed scenarios and Defense Against the Dark Arts professor Umbridge software demos. When developing practice takes a completely theoretical approach to teaching scenarios or hands-on training, focus on the defensive spells. During her first Defense Against most important and/or complex topics first. the Dark Arts lesson to Harry and his fellow fifth- How can learners practice what they have year classmates, Umbridge explains how students just learned? For instance, in e-learning will learn the theory of defensive spells so they will courses, you can create software simula- be able to perform the spell during end-of-year ex- tions or branching scenarios with Captivate. aminations. Then throughout all her lessons, stu- In instructor-led courses, you can use a test- dents either read silently from their textbook or copy ing environment with pre-defined exercises notes from the board. They never get to receive any and scenarios, or use software simulations. hands-on practice with any of the spells in her Depending on what the learning objectives classroom (Order of the Phoenix, pp. 238-244). are, you can incorporate hands-on training. • Encourage students to handwrite their notes, or at least not type information Lesson Analysis verbatim. When students handwrite their While ensuring a safe, risk-free learning environ- own notes, they write down only what is ment can be a good thing, Umbridge goes too far. most important to them, this synthesizing First, she shows utter disregard for her students’ the information they’re taking in and making abilities and knowledge base. Although she does it their own. introduce course aims during her class, she teaches • Consider creating guided notes. If your first-year basics to fifth year students who had al- learners are not generally note-takers and ready demonstrated knowledge of their course ma- need a bit of guidance, create guided notes terial over the years. Her teaching style also leaves for them. Guided notes are generally pre- much to be desired—the students either read silent- generated notes of the lesson or presenta- ly or copy notes verbatim from the board. Regarding tion, with fill-in-the-blanks on key words and her approach to note-taking—people do learn more phrases. During the course, students fill in when they hand-write vs. type their notes. When these notes as they go, thus engaging with you handwrite notes, you tend to synthesize the lec- the information. When creating your own ture information, thus making the information your guided notes, first identify the most im- own. portant items. Those items will be the blanks. Make sure what you use as blanks Lesson Takeaways is not trivial information. • Know your audience. You should do this first, even before defining learning objec- Lockhart: Pesky Pixie Release tives. Think about who will be using your On the flip side of Umbridge’s wand-free lesson, materials. What do they already know? Professor Lockhart takes the opposite approach by What do they NEED to know to perform the introducing an all-practical lesson without ANY

108 2018 STC Technical Communication Summit Proceedings Lessons Learned: What Harry Potter Professors Teach Us About Instructional Design background material. First, he draws the class’s at- to use a bit of drama or humor, just make tention to a large, covered cage placed on his desk. sure your lessons contain substance. After a few dramatic utterances, he unfurls the cover, revealing a cage full of little razor-sharp teethed blue creatures called Cornish pixies. As he tells the Binns: Spookily Boring Lessons class to “let’s see what you make of them,” he Professor Binns teaches History of Magic at Hog- opens the cage door and releases the pixies into warts. What sets him apart from other professors is the classroom. Soon, the pixies wreak havoc upon that he’s an actual ghost. Every day, he materializes the classroom, from upturning wastebaskets to even from the wall and delivers his lecture. Too bad his hanging a student from the chandelier by his robes. classroom entrance is the most exciting aspect of Only then does Lockhart finally tell the class to class. He puts the class to sleep with his voice— round up the pixies. No one knows how, except for described as a “flat drone like an old vacuum clean- Hermione, who zaps the creatures with freezing er.” (Chamber of Secrets, p. 148) charms to immobilize them. She already knew of this charm before this class. (Chamber of Secrets, pp. 100-102) Lesson Analysis Plain lecture, especially accompanied by a mono- Lesson Analysis tone vocal delivery, is extremely inefficient at cap- turing students’ attention, as evidenced by the stu- Although hands-on experience is a wonderful way dents constantly sitting in a state of stupor during to learn, several key elements are missing from his lessons. Even exciting subjects such as goblin Lockhart’s lesson. First, Lockhart should have ex- wars become dry and dull with Binns’ teaching style. plained what Cornish pixies are. He never explains what they are, or how to defend against them. Since this was the first day of school, it is highly unlikely Lesson Takeaways that anyone would have read the textbook in ad- • Incorporate variety into your lesson. vance, except for Hermione Granger, the smartest While lectures can be effective for convey- student of Harry’s class. Second, Lockhart could ing vast bits of information, they quickly lose have demonstrated to the class how to use the impact if they don’t engage as many senses freezing charm on the Cornish pixies, instead of as possible. Include such elements as im- creating unnecessary drama with his fake “peski- ages, video clips, graphs, charts, and other piski” charm. Finally, and most importantly, Lockhart audio/visual elements. Better yet, don’t de- should have told the students what they needed to pend solely on lectures to convey infor- do BEFORE he opened the cage, instead of waiting mation. Include group discussions, exercis- until they were distracted by the pixies’ troublesome es, and other activities that invite participa- antics. tion. • Don’t do all the talking. Another good way Lesson Takeaways to maintain student interest is by including discussion questions every now and then, • Make sure the lesson is complete, and either to have students recall facts or offer that you have enough activities to sup- opinions on the topics at hand. Just make port all your learning objectives. For in- sure your discussion Again, don’t be afraid stance, if your objective is to have the class to use visuals (which we will cover in greater capture the pixies, determine what they detail, with Professor Moody’s lesson). need to know to do so. In this case, they will need to learn or know the freezing charm. • Pay attention to your vocal delivery. Avoid monotone. Make sure you talk clearly • If conducting an activity, explain the and not too fast. Don’t be afraid to show ex- steps beforehand. Can you imagine what citement; just don’t over-exaggerate (or re- would have happened if Professor Sprout sort to monotone) or else your learners will had not warned the class about the man- focus more on your delivery and less on drake’s fatal cry before showing the class your message. how to repot them? • Show passion for your subject, but not for disguising ineptitude. Don’t be afraid

2018 STC Technical Communication Summit Proceedings 109 Jamye Sagan

Moody: Cursed Demos Not So boggarts, creatures that physically embody one’s deepest fear. In teaching his class this complex Cursed After All charm, he breaks each component into manageable Professor Moody introduces his students to the components, to ensure his students completely un- three main illegal curses, known as the Unforgivea- derstand what they need to do (Prisoner of Azka- ble Curses—Imperius (mind control), Cruciatus (tor- ban, pp. 132-139). ture), and Avada Kedavra (killing). Because he believes his students need to witness the curses in Lesson Analysis action to better understand how to defend themselves against them, Moody demonstrates each Lupin’s boggart lesson is a good example of how to curse on an enlarged spider. First, in showing the chunk content to make it more manageable. First, Imperius curse, Moody makes the spider do various he introduces the lesson with several leading ques- crazy activities on his command. Then in showing tions to gauge what the class already knows about the Cruciatus curse, Moody tortures the spider until boggarts. After establishing that knowledge base, its entire body twitches violently in pain. Finally, in Lupin then has the class practice saying the charm showing Avada Kedavra, the spider drops dead in a aloud. Once the students can chant the incantation green flash of light (Goblet of Fire, pp. 211-217). properly, Lupin invites student Neville Longbottom to help him demonstrate how to fight a boggart. He guides him through the process of how to make his Lesson Analysis greatest fear look comical –the expected outcome Lesson demonstrations prove powerful indeed for of the lesson. With Lupin’s encouragement, Neville Moody’s students—much more than if they had performs the charm easily, with great success. Lu- read them in a book. For instance, during the Cruci- pin then invites the rest of the class to practice the atus curse demo, student Neville Longbottom cring- charm. Throughout the lesson, Lupin offers feed- es in pain. His parents had been tortured into in- back to make sure students are performing the spell sanity with this curse. Thanks to the green flash of correctly. light from the Avada Kedavra demonstration, Harry learned exactly how his parents had died. The en- Lesson Takeaways tire lesson shows that visuals can pack quite the punch in your curriculum. • Divide content into manageable chunks. If you present too much information to your learners at once, they may get overwhelmed Lesson Takeaways and start tuning out information. A good rule • When possible, show rather than tell. As of thumb is 15-20 minutes per module or ac- mentioned in the previous section, lessons tivity. have greater impact when they involve mul- • When developing training, break it up in- tiple senses. to smaller chunks—also known as • Embrace the power of visuals. One way chunking—to make it easier to digest. If of doing so is by creating job aids that neatly developing e-learning courses, break up summarize the material at hand. When I the content into several modules. For create job aids, I focus solely on what needs instructor-led courses, mix up activities to be covered. I like to keep my job aids within the given classroom time. brief, no more than one or two pages per • Chunking training content also makes topic. When possible, I use screenshots and course updates much easier; you only pictures to show the process. I also use ta- have to update the small chunk vs. the bles and other methods of displaying data entire course. so it is more easily digestible. • When chunking your training, consider: Think of how steps are broken down. Lupin: Defeating Boggarts with Think of the topics you are covering. If you are covering multiple topics, group Well-Paced Lesson related ones together. In his first lesson, Defense Against the Dark Arts • Provide encouragement and offer feed- Professor Lupin teaches his students how to fight back. Just as Lupin commented on Neville’s

110 2018 STC Technical Communication Summit Proceedings Lessons Learned: What Harry Potter Professors Teach Us About Instructional Design

performance and his confidence in his abili- http://theelearningcoach.com/elearning_design/ ties, so should you do the same with your chunking-information/. students. S, Jessie. “Note-Taking: Writing vs. Typing Notes.” • Feedback needs to be specific. Instead StudySkills.com (22 August 2016). of just saying “Good job!” or “Wrong, https://studyskills.com/students/note-taking/. please try again,” give a reason. Explain Shaw, Adam. “Three Tips for Writing Measurable why. For instance, when developing e- Objectives.” The Online Learning Curve—Best learning courses, I incorporate several Practices in Online Higher Education (2 “Test Your Knowledge” questions November 2011). throughout the course. I base these http://www.learninghouse.com/blog/publishing/3 questions on the defined objectives, and -tips-for-writing-measurable- provide specific feedback. When the objectives#sthash.PNRBdacM.dpuf. learner answered the question, they Simmons, Kerri. “Incorporating Real-World would immediately know if they an- Experiences in E-Learning.” Training Industry swered correctly or not, and more im- (21 January 2015). portantly, why. Meaningful feedback http://www.trainingindustry.com/e- helps the learner know not only what learning/articles/incorporating-real-world- they did correctly, but also what they experiences-in-e-learning.aspx. need to work on. Stenger, Marianne. “5 Research-Based Tips for As shown here, various professors at Hogwarts ex- Providing Students with Meaningful Feedback.” hibit both positive and negative aspects of lesson Edutopia (6 August 2014). delivery and instructional design. The most effective http://www.edutopia.org/blog/tips-providing- ones keep their students engaged with a variety of students-meaningful-feedback-marianne- relevant activities. Plus, we can learn from even the stenger. most ineffective professors, since they show us Tucker, Christy. “Intrinsic and Instructional what not to do. Feedback in Learning Scenarios.” Experiencing E-Learning (19 March 2015). https://christytucker.wordpress.com/2015/03/19/ intrinsic-and-instructional-feedback-in-learning- Resources scenarios/. Amin, Houra. “4 Dos and Don’ts When Providing United States Department of Labor, Occupational Feedback.” eLearning Industry (2 April 2018). Safety and Health Administration, Intervention https://elearningindustry.com/providing- Central. Draft Model Training Program for feedback-dos-donts. Hazard Communication. https://www.osha.gov/dsg/hazcom/MTP101703. Dalto, Jeffrey. “How to Chunk Training Materials.” html. Convergence Training (31 October 2014). http://blog.convergencetraining.com/chunk- training-materials. References Eades, John. “Why Microlearning is HUGE and How to Be A Part Of It.” eLearning Industry (2 July Rowling, J.K. Harry Potter and the Chamber of 2014). https://elearningindustry.com/why- Secrets (New York, NY: Arthur A. Levine microlearning-is-huge. Books), 1999. Rowling, J.K. Harry Potter and the Goblet of Fire “Guided Notes: Increasing Student Engagement During Lecture And Assigned Readings.” (New York, NY: Arthur A. Levine Books), 2000. Intervention Central. Rowling, J.K. Harry Potter and the Order of the http://www.interventioncentral.org/academic- Phoenix (New York, NY: Arthur A. Levine interventions/study-organization/guided- Books), 2003. notes-increasing-student-engagement-during- Rowling, J.K. Harry Potter and the Prisoner of Malamed,lecture Connie.-. “Chunking Information for Azkaban (New York, NY: Arthur A. Levine Instructional Design.” The eLearning Coach Books), 1999. (n.d.).

2018 STC Technical Communication Summit Proceedings 111 Jamye Sagan

Author Contact Information Jamye Sagan Pharmacy Communication Advisor H-E-B 646 S. Flores Avenue San Antonio, TX 78204 210.938.8526

Author Biography As the Pharmacy Communication Advisor for H-E- B, Jamye helps design training programs and materials for various projects and initiatives in the pharmacy department, including use of their proprietary prescription dispensing software and health screening programs. She also manages communications between the corporate office and the store pharma- cies. A Senior Member of STC, Jamye volunteers with the Instructional Design and Learning SIG with So- cial Media and Surveys. Jamye also belongs to the Policies & Procedures SIG and the Technical Edit- ing SIG. She also volunteers at the Society level, as a member of the Community Affairs Committee and as the 2017-18 chair of the Community Achieve- ment Award and Pacesetter Award committees. When not making “sense out of the senseless” in the tech comm world, Jamye enjoys transforming yarn into pretty and useful objects. She also enjoys reading and watching Harry Potter for the ump- teenth time. Although she admits to not becoming a fan until the first movie came out in 2001, she’s attended nearly every midnight screening and book release ever since. She even belongs to a virtual group devoted to fiber crafts and Harry Potter.

From Technical Writer to Content Strategist Melanie Seibert

The world needs more content strategists. As a tech writer, you possess valuable skills that uniquely equip you to “do content strategy.” In this talk, I’ll recap my own journey, plus provide an overview of content strategy, reasons why you should pursue this exciting field, and specific tactics that you can use to successfully transition from technical writer to content strategist.

Planning for content. Tasks in this category in- One Content Strategist’s Story clude: The year was 2009. Working as a technical writer • User research at a software company, I was asked to work on • Inventorying and auditing content my company’s website redesign. The request to work on this project consisted of my boss porting • Helping the business define its goals all the web pages to a new platform, then asking Designing the content. Tasks in this category my co-worker and me to sift through the results. include: Did I mention this happened on a Friday after- • Defining brand voice and tone noon and I was supposed to leave town for a • Creating page templates to support writ- weekend trip at 5pm? ers My co-worker and I spent weeks sifting through • Creating a content matrix to track content the (already migrated) content, unearthing documentation that no one knew existed. Some of it Delivering the content. Tasks in this category many years old. include: Fast forward to today. I work as a Sr. Content • Modeling content for implementation in a Strategist on a team that designs and builds digi- content management system (CMS) tal products like apps and chatbots. I’m con- • Mapping out the content workflow, includ- stantly learning, and I work with some of the ing approvals and publication process smartest people I’ve ever met. • Defining the channels and platforms you How did I get to this point? In 2009, I learned should use to reach your audience (in- about a field called content strategy. cluding websites, social media, email, apps, and more) Maintaining the content. Tasks in this category What Is Content Strategy? include: Here’s the official definition from Kristina Halvor- • Defining roles and responsibilities for son, author of the groundbreaking book Content content governance Strategy for the Web: “Content strategy guides • Planning and conducting rolling audits planning for the creation, delivery, and governance of useful, usable content” (Halvorson, 2012). The Opportunity for Technical Here’s the definition I tell my parents: “What a Writers newspaper editor does, but for websites.” You may have several reasons for considering a This definition works, because it underscores career in content strategy— how much effort goes into digital content. The duties of a content strategist encompass: 113 Melanie Seibert

• You enjoy strategic planning and The demand for content strategy skills has never connecting people across the been higher. organization. Technical writers tend to have skills that make for • You want to further your career and successful content strategists: in-crease your salary. • Adaptable. You probably work with • You want to meet amazing people. teams on technologies that change • You want to challenge yourself quickly. You can change priorities and professionally. are always looking for ways to improve Whatever your reason, you can do it. The com- your documentation process. munity of Content Strategists is amazingly sup- • Resourceful. Often cast in the role of portive and accepting, full of incredible people tech journalist, you have to extract infor- ready to share their knowledge. mation from subject matter experts, or And most of all, the need is there. Just check out printed materials. If you have trouble get- the Google Trends data for "Content Strategy" as ting information from one source, you a search term from 2004 to 2017 (Google know where else to look. Trends), in Figure 1. • Curious. You’re always learning about technology and tools. Otherwise you According to The Creative Group's 2018 Salary wouldn’t be here at the Summit! Guide, the average content strategist makes $73,000 annually—about 6% more than the average technical writer.

Figure 1. Interest in Content Strategy has nearly quadrupled since 2004.

114 2018 STC Technical Communication Summit Proceedings From Technical Writer to Content Strategist

According to The Creative Group's 2018 Salary • You can't fix what you don't know about. Guide, the average content strategist makes And the audit shows you all your content. $73,000 annually—about 6% more than the aver- You shouldn’t move forward with any age technical writer. content creation for a website redesign without knowing what content you currently have. How to get started • The content audit is also important because when you see that the website Step 1: Read Content Strategy Books. needs work, and you need time and money to do that work, you have to go to I recommend starting with these books, in this or- your boss. This is what we call "getting der: buy-in." 1. Halvorson, Content Strategy for the Web The concept behind a content audit is simple: 2. Sheffield, The Content Strategist’s Bible you click through your site and you make a list of 3. Casey, The Content Strategy Toolkit the pages on it. 4. Bloomstein, Content Strategy at Work Start at the top-level navigation, then drill down through each section, listing each page as you Step 2: Conduct a Content Audit go. You can start “doing” content strategy right now. To create your inventory, you’ll need some type of spreadsheet software. The most popular Conducting basic content audit can give you choice is Microsoft Excel, but you can also use deep insights into the state of your content—and Apple Numbers if you have a Mac. I also use a powerful testimony to the value of your project. Google Docs. Use what you're comfortable with. The content audit is the first strategic step that The process will be the same no matter which most of us can take right away to improve our program you use. content. And it's powerful for 2 reasons:

Figure 2. U.S. starting salaries, in dollars (The Creative Group, 2018)

2018 STC Technical Communication Summit Proceedings 115 Melanie Seibert

Figure 3. Example of a content audit for a nonprofit organization Step 3: Follow Content Strategists on Plus, you don’t need to know how to design or Social Media code to get started. Turns out, there are lots of amazing Content Not sure what to write about? Here are some Strategists on Twitter! Where to start? Here are a thought-starters: couple of excellent lists: • Book review—Read one of the books I • Colleen Jones’ ContentStrategy list mentioned in this post (or something else!) and share your thoughts. • Heinz Wittenbrink’s Content Strategy list • Your story—Who are you and what do If you’re more of a Facebook person, check out you do? Share why you became inter- these Facebook groups: ested in content strategy. • Content Strategists. This is a very ac- • Critique a website’s (or app’s) content— tive group populated by a good mix of ex- Be careful with this one; it’s easy to be a perienced and new Content Strategists. little harsh in the beginning, before you • Become a Content Strategist. My group know just how difficult it is to do content for newcomers to ask questions and dis- well. (I speak from experience.) But it is cuss how to get into Content Strategy. possible—and informative to others—to diplomatically share examples of well Michael Metts’s Content + UX Slack group is an- done (or poorly done) content. other amazing place to interact with tons of Con- • Thoughts on a trend—What’s trending in tent Strategists. Join by filling out the application. your industry? Or with Content Strategy in general? If you have thoughts to share, Step 4: Attend a Content Strategy go for it! Meetup • Thank a mentor—Is there someone you There’s nothing like getting facetime with other know, whether in person or online, who content strategy enthusiasts. Search Meetup to helped you in your career? What did they see whether there’s a Content Strategy Meetup do well? What can the rest of us learn near you! from them? Low-cost blog hosting options include Word-Press, Step 5: Start a blog Squarespace, and Medium. Note that Me-dium doesn’t let you host your own domain (like “Who, me?” Yes, you. You may be new, but you mysite.com). It’s still helpful for getting eyeballs on have a unique perspective that others will be in- your posts. Think of it as more of a combina-tion terested to hear. blogging site and social network.

A blog shows how you think, and that you’re ex- cited and passionate about your field. Employers Step 6: Keep Learning! like to see both those things. Setting up a blog If you’re like me, you learn best when a little these days is simpler and cheaper than ever. structure's involved. 116 2018 STC Technical Communication Summit Proceedings From Technical Writer to Content Strategist

Today, there are a handful of content strategy The Creative Group. “2018 Creative & Marketing courses you can take. Most are in person; oddly, Salary Guide.” Robert Half (2018). there are few online courses in content strategy https://www.roberthalf.com/salary- (mine being the main exception I’m aware of). guide/creative-and-marketing. Sure, Google turns up lots of results, but most Google Trends. Search on “content strategy” courses have to do with content marketing; if 2004–present. Google Trends (2018). you’re looking for product- or UX-focused content http://trends.google.com. strategy, pickings are slimmer. Halvorson, Kristina and Rach, Melissa. Content Fortunately, there are several good options. Strategy for the Web, 2nd ed. (Berkeley, CA: Google is your friend here. To get started, feel New Riders), 2012. free to take my free email course, Become a Sheffield, Richard. The Content Strategist’s Bible Content Strategist at my website, prosekiln.com. (CreateSpace Independent Publishing Platform), 2009. Also, the Content Strategy Alliance offers a mentorship program, as well as tons of examples of actual deliverables. Author Contact Information The community of Content Strategists is very Melanie Seibert welcoming and supportive. Join us! Senior Content Strategist WillowTree, Inc. 107 5th St SE Charlottesville, VA 22902 Resources [email protected] Halvorson, Kristina. “Content Strategy for 512.987.5673 Everything.” Slideshare (6 July 2015). https://www.slideshare.net/khalvorson/ Author Biography conten t-strategy-for-everything. Seibert, Melanie. “Become a Content Strategist.” A former technical writer, Melanie Seibert now Prose Kiln. serves as the Senior Content Strategist at Wil- https://www.prosekiln.com/courses/. lowTree, a mobile product agency. Melanie has created documentation for cPanel and Rackspace. She has also taught content References strategy at General Assembly and helped For- Bloomstein, Margot. Content Strategy at Work tune 500 companies develop effective content for (Waltham, MA: Morgan Kaufman), 2012. their websites during her time at Razorfish. She Casey, Meghan. The Content Strategy Toolkit opines about content-related topics on her blog, (Berkeley, CA: New Riders), 2015. Prose Kiln, at https://www.prosekiln.com/.

A Method for the Madness: Managing Complex Documentation Projects Jennifer Shumate, Senior Member

Managing a large, complex documentation project is equal parts art and science. Left to its own devices, it can quickly devolve into chaos. Learn how to apply a method to control the madness, using strategies from a real-world Flare project that supports eleven unique software applications. This paper will give you practical tips for getting your documentation project under control. Learn how a strict taxonomy, content reuse, and simplified graphics can all work together to make your life easier.

The Impossible Project to use Flare to implement these techniques. Many of these features are available in similar authoring Three years ago, my company assigned me to a tools. new software project, the OneSync® software suite. On my previous project, I was responsible for providing documentation for a single software Develop a Strict Taxonomy application. Foolishly, I assumed that my role on One key element of managing a large documenta- the OneSync® project would be similar. tion project is to keep it well-organized. I have I could not have been more wrong. found that implementing a strict taxonomy for all of your project files is invaluable to a well-orga- At the time, the OneSync® suite encompassed nized project (White, 2012). A strict taxonomy al- four unique software applications. Each of these lows you to easily identify how all of your content applications used a common user interface, with fits into the overall project. Your taxonomy should many overlapping modules between each applica- be reflected in all files in the project, including top- tion. Because of the enormous amount of shared ics, images, and snippets. Common elements content, it made sense to use one Flare project to within topics, such as introductions and field defi- support the documentation for all four applica- nitions, should use the same bookmarks and simi- tions. lar language. In the years since, the OneSync® suite has grown You can use any taxonomy that you like, as long into eleven software applications. All eleven of as you use it consistently. Some of the guidelines these applications are still supported by that same for my taxonomy include: Flare project. It now contains over 400 topics, 1000 images, 400 snippets, and has over 14,000 • Three-to-four-letter prefix for each subject conditions applied. Managing this project has area. The file names for all content related pushed both my content management skills and to this subject—topics, images, and snip- my sanity to new heights. pets—begin with this prefix. I will give you practical tips on how to manage a • Three-to-four-letter abbreviation for each large, complex documentation project. These tips application in the OneSync® software. All include: output items for each application—targets, condition tags, destinations—use this ab- 1. Develop a strict taxonomy. breviation. 2. Reuse, reuse, reuse! • Whenever possible, snippet and image file 3. Create simplified UI graphics. names match the file name for the topic they are related to. The examples given in this paper are from my real-world Flare project. However, you don’t have

118 A Method for the Madness: Managing Complex Documentation Projects

• If multiple application-specific screenshots • A separate variable set that is only used are required for a particular section, the for snippets. application abbreviation is added to the These conditions and variables are applied at the end of the image name. topic and snippet level, rather than at the output • An identifying word for common sections, level. Using these strategies, I have created ap- such as introductions, field definitions, and proximately 400 snippets that are used in over button definitions. All bookmark names 1600 different places. and snippet names use this identifying word, regardless of the subject area. My Flare project contains a set of numbered condition tags that are used exclusively for snippets. I Example: An introductory topic about static BHA often use this strategy in sections with overlap- analysis, in the Mechanics Analysis section of the ping content that also has some differences, such user guide. The topic includes the introduction as button definitions, field definitions, and task in- and button definitions. structions. • Subject area prefix = AMBS To use snippet conditions and variables: • Topic = AMBS_About.htm 1. Assign a condition to a particular subject • Section = Introduction area within a section of your content. • Bookmark = About 2. In each snippet, apply the assigned condi- • Image (OneSync® Planning) = tion to each piece of content that is rele- AMBS_Plan.png vant to the subject area, e.g. a table row in • Image (OneSync® Monitoring) = a list of field definitions or a list item in AMBS_Mon.png task instructions. • Snippet name = AMBS_About.flsnp 3. In each snippet, insert variables for navigational references and other text-based • Section = Button definitions items. • Bookmark name = UseTab 4. In all topics for the subject area, set the • Snippet name = AM_UseTab.flsnp snippet conditions to include the assigned condition and exclude all others. Reuse, Reuse, Reuse! 5. In all topics for the subject area, choose the appropriate definitions for each varia- Another key element for managing a large docu- ble used in the snippets. mentation project is to maximize your content reuse whenever possible. When you have a large The figures below show an example of this strat- amount of content, you don’t have time to make egy in action. The first figure shows a snippet with the same updates in multiple places. Content re- a table for button definitions. This snippet is used use becomes more important than ever. Snippet in seven different topics in the Hydraulics Analysis variables can increase your reuse, while reducing section of the user guide. The colored shaded ar- the number of conditions used. Separate condi- eas show where snippet conditions have been tion tags for outputs and snippets can also in- used to identify content for each of the subject ar- crease your reuse. eas within the Hydraulics Analysis section. The gray shaded areas show where variables have It's common to use snippets in places where your been used for navigational references and subject content is identical. You can also use snippets to area names. reuse content that is similar, but not identical. I have two primary strategies that allow me to re- The second figure shows the resulting content in use similar chunks of content: one of the seven topics where this snippet appears. • A separate condition tag set that is only used for snippets.

2018 STC Technical Communication Summit Proceedings 119 Jennifer Shumate

Figure 1. Snippet for button definitions in the Hydraulics Analysis section

Figure 2. Button definitions for the Displacement subject area, within the Hydraulics Analysis section Snippet-only conditions can be used for many dif- • Torque and drag analysis, within the Me- ferent purposes throughout your content. The key chanics Analysis section. to successfully reusing content in this way is to • Time-based graphs, within the Dash- make sure that each condition tag is only used for boards section one subject area within each section of content. In the examples below, in the Hydraulics Analysis Example: The Snippet_2 condition tag is used to section, the Snippet_1 condition is only used for identify content for: content specific to hydraulics snapshot analysis. • Hydraulics parametric analysis, within the However, it can also be used for other purposes Hydraulics Analysis section. in other sections of your content. • BHA static analysis, within the Mechanics Example: The Snippet_1 condition tag is used to Analysis section. identify content for: • Depth-based graphs, within the Dash- • Hydraulics snapshot analysis, within the boards section. Hydraulics Analysis section.

120 2018 STC Technical Communication Summit Proceedings A Method for the Madness: Managing Complex Documentation Projects

Create Simplified UI Graphics screenshots modified to block out the irrelevant portions of the user interface. They focus the One of the biggest challenges that I faced with user’s attention on the relevant parts of the UI. this project was screenshots. The OneSync® soft- Most importantly for me, though, is that simplified ware is modular, meaning that many modules ap- UI graphics allow you to use a single graphic for pear in multiple applications. And although the multiple applications or purposes. content of a module might be identical across all of the applications, the rest of the UI around the Example: The Bit calculation module appears in module very rarely was. The result is that I had a six of the OneSync® applications. Although the lot of screenshots to manage, and they constantly module itself is identical in all six applications, the needed to be updated. interface around it is different. Then I discovered simplified UI graphics By blocking out the parts of the interface that are (Holnagel, 2015). Simplified UI graphics are not relevant to the Bit calculation module, I can use the same image for all six applications.

Figure 3. The Bit calculation module in OneSync® Simulation

2018 STC Technical Communication Summit Proceedings 121 Jennifer Shumate

Figure 4. The Bit calculation module in OneSync® Monitoring

Figure 5. Simplified UI graphic for the Bit calculation module

122 2018 STC Technical Communication Summit Proceedings A Method for the Madness: Managing Complex Documentation Projects

This strategy has allowed me to eliminate many Lambe, Patrick. Organising Knowledge: nearly-duplicate screenshots. Before I started us- Taxonomies, Knowledge, and Organisational ing simplified UI graphics, I had an average of 114 Effectiveness (Oxford, UK: Chandos screenshots per application. Now, I have an aver- Publishing), 2007. age of 72 screenshots per application. When Lavallee, Johanne. “Organize the Organizers.” there are updates to the UI—which is often—I Intercom (July 2015): 13-15. have far fewer screenshots that need to be up- Schneider, Kate. “MadCap Flare Refresh: dated. Reviewing the Basics to Work Smarter.” Intercom (January 2017): 20-22. Conclusion Self, Tony. “Levels of Re-Use.” Adobe Technical Communication Blog (13 May 2013). https:// These techniques can be applied to any docu- blogs.adobe.com/techcomm/2013/05/tr mentation project, large or small. When I inherited ends-levels-of-re-use.html. a chaotic, messy Flare project, they helped me to Semp, Monique. Leveraging Structured get the madness under control. The original pro- Authoring/DITA Techniques When All You ject had little to no organization. There was no Have Are Unstructured Tools (Proceedings, consistency in the file names or the folder struc- STC Summit Conference, 2017). ture. There was no reuse whatsoever, so it was Sermeno, Jose. “Tweaking the Content Inside of riddled with duplicate content. When there were Snippets Using Conditions.” MadCap updates to the UI, the documentation often had to Software Blog (15 Feb 2012). be updated in several places. https://www.madcapsoftware.com/blog/2012/0 Today, my Flare project is tightly organized with a 2/15/tweaking-the-content-inside-of-snippets- consistent naming convention for all files. Content using-conditions. is reused whenever possible, so there is very little Stoecklein, Paul. “Five Ways to Improve Your duplicate content. Using simplified UI graphics al- MadCap Flare Project: Part 5—Conditions in lowed me to further reduce the updates that are Chunks.” MadCap Software Blog (25 Feb required when there are changes to the interface. 2016). All of the techniques discussed are fairly simple https://www.madcapsoftware.com/blog/2016/0 concepts. However, they have proven to be inval- 2/25/five-ways-improve-flare-project-part-5- uable to me. Because of them, I am able to sin- conditions-chunks. gle-handedly support eleven unique software applications. References Holnagel, Josh. Simplified User Interface Graphics for User Tutorials (Proceedings, Resources STC Summit Conference, 2015). “Using Simplified User Interfaces (SUI) in Help White, Leigh. Taxonomy. Do I Need One? Content.” TechSmith Blog (25 July 2014). (Proceedings, STC Summit Conference, https://www.techsmith.com/blog/devcorner- 2012). simplified-ui-sui. Gerber, Beth. “Keeping It Clean—Ways To Streamline Content in RoboHelp.” Adobe Author Contact Information Technical Communication Blog (5 Feb 2015). Jennifer Shumate https://blogs.adobe.com/techcomm/2015/02/k Technical Supervisor eeping-it-clean-ways-to-streamline-content-in- Weatherford International robohelp.html. 11909 Spencer Rd Hackos, JoAnn. Introduction to DITA: A User Houston, TX 77041 Guide to the Darwin Information Typing 713.983.5514 Architecture (Denver, CO: ComTech Services, Inc.), 2011. Hedden, Heather. The Accidental Taxonomist (Medford, NJ: Information Today, Inc.), 2010.

2018 STC Technical Communication Summit Proceedings 123 Jennifer Shumate

Author Biography Jennifer Shumate is a lone technical writer for the OneSync® software suite, a drilling engineering software package for planning and monitoring wells. Jennifer is deeply passionate about using technical communication to improve the user experience. She has ten years of experience in the technical communication field, and she’s spent the last seven years pushing MadCap Flare to its limits. Before joining Weatherford, she worked at Shell Trading and Borland Software. She earned a B.A. in English from Texas State University, and she was a judge for the 2016 STC Regional Com- petition for the Houston-NYC region. She is a senior member of STC and belongs to the User Expe- rience SIG.

An Information Experience (IX) Maturity Model for Organizational Transformation Sudhir Subudhi

Currently, many organizations know the benefits of User Experience (UX) or Information Expe- rience (IX) in particular for the content industry. To them these subjects are fascinating, yet are just theory. Putting it into practice organizationally is the real challenge. Many are unaware where they are, where to start and where to end.

The sample IX Maturity Model solves this problem. It's based on the proven principles of game science. With this, now companies can assess their current position in IX quickly, and develop a roadmap to improve their position from the current level to the desired level.

IX Maturity Model

Figure 1. IX maturity model

Broadly, the model is divided into five stages. Every stage has a name, a spread in the com- • Stage [1]: Unrecognized pany, and duration to exercise the stage in the company. It stands on four critical pillars: People, • Stage [2]: Recognized Skills, Activities, and Deliveries. To implement a • Stage [3]: Invested particular stage, get the listed people with the • Stage [4]: Optimized listed skills, ask them to do the listed set of activi- • Stage [5]: Cultured ties, and in the end harness or store the listed

125 Sudhir Subudhi deliveries. Run this cycle for a couple of releases The group can continue doing stage [1] activities or months as per the mentioned duration. and storing stage [1] deliveries. In addition, now, encourage the group to perform team trials to As a company, you could follow the sample Ma- work on bigger features or a suite of features. turity Model as it is, or you could alter it according They all could stand together and voice out in offi- to your need and environment. To get the most cial communications and events. They could per- out of it, it’s recommended that you start from form bigger user surveys. And they could make Stage [1] and progress to the desired stage improvement proposals with Proof of concepts phase-wise. If you find you have already imple- (PoC) and Return on Investment (ROI) projec- mented some of the starting stages, and you are tions. midway into the model, you can start from the stage you can relate yourself to. Ask the group to store or archive the deliveries that come as a result of the performed activities. These deliveries are SIG mailing list/wiki, user Stage [1]: Unrecognized survey reports, proposals, ROI projections, and This is the first stage into the model. To imple- proof of concepts. ment this stage, get highly experienced technical Follow this in cycles for six months or two-three communicators having skills such as good under- releases to get expertise in this stage. When a standing of users, business, project, and process. product level manager sees potential in new and Encourage them to perform self-research and in- better information deliveries, approves the pro- dividual trials on standard features that they can posals to implement it in a particular project, com- showcase. They could conduct user interviews. mits to make investment in it, you make a smooth They could speak out through discussions, transition to the next stage. presentations, and blogs. They can make improvement plans. Stage [3]: Invested Ask them to store or archive the deliveries that This is the third stage into the model. You now come as a result of the performed activities. have a team set to implement the new ideas in full These deliveries are technical blogs, discussion scale in a project to make content deliveries that threads, paper presentations, interview findings, provides an experience to a specific client. You and improvement plans. would need involvement, support and guidance of Follow this in cycles for six months or two-three people like Content Strategist, Project Manager, releases to get expertise in this stage. At the end, or Business Head, with skills such as business you will find people starting to recognize infor- acumen, content strategy, and project manage- mation experience knowledge, activities, and ment. goals. Your team might find a product manager, a The group can continue doing stage [2] activities dev lead, or a test lead thinking alike to better the and storing stage [2] deliveries. In addition, now information deliveries. When you find allies with you send them for formal training on UX/IX. Ask same mindset and vision from other cross func- the team to define IX tasks and assign them to re- tional teams, you make a smooth transition to the sources. They could now perform tasks such as next stage. user research, prototyping, content delivery, user testing, and feedback management in full scale. Stage [2]: Recognized Ask the group to store or archive the deliveries This is the second stage into the model. You are that come as a result of the performed activities. now having a virtual and loosely connected team These deliveries are IX tasks with definitions, user of like-minded people, with skills such as good un- research report, low and high level prototypes, derstanding of users, business, project, and pro- content deliveries, business case study with ROI cess. You could name it as a Special Interest statistics. Group (SIG) formed to better information deliver- Follow this in cycles for two-three releases to get ies. expertise in this stage. You can implement it in multiple projects targeted for multiple clients. When the higher management starts to see the realized value through the business case studies

126 2018 STC Technical Communication Summit Proceedings An Information Experience (IX) Maturity Model for Organizational Transformation and ROI statistics, they would want to go for a The following table lists the tasks you should com- companywide implementation across all the run- plete while working in different stages of a project. ning projects. Here you make a smooth transition It mentions what all tools you can use for this and to the next stage. what all targets you can achieve and store.

# Stage IX Tasks Tools Target

1 User analysis, task Surveys, Meetings, In- Offline: Stories, Personas, Pat- analysis, requirement terviews, Involvement Manual terns, Inputs, Recom- analysis mendations, Sugges- Online: tions, Requirements, Survey Monkey, Problems Skype, Hangout, Lync, Forums

2 Design Storyboarding, Wire- Whiteboard with sticky Storyboards, framing, Preparing notes, Pen and paper, Wireframes, Mockups, mockups, Prototyping, Balsamiq, PowerPoint, Prototypes Prototype improve- MS Word ment

3 Development Prototype implementa- Content development Content deliverables tion, Content develop- tools ment

4 Testing Reviews and testing MS Excel, Defect man- Review reports, de- agement tools, Email fects, Improvement suggestions

5 Release Release Publishing, Content publishing Content deliverables Build tools

6 Maintenance and im- Feedback manage- Defect management Analytics reports, Im- provement ment, Defect manage- tool, Meetings, Analyt- provement plans and ment, Retrospective ics tools, Survey Mon- proposals, Defect fix- meetings, Expert re- key, Email ing reports view, Analytics

Table 1. IX Tasks, Tools and Targets in Different Stages of a Project Stage [4]: Optimized mandatory to work on. Ask the team to define IX measurement metrics and score cards, and track This is the fourth stage into the model. You are or monitor the content deliveries through these set to implement the IX activities in all the projects utilities. running across the company. May be you want to make it mandatory for all. You would need in- Ask the people to store or archive the deliveries volvement, support and guidance of a Process that come as a result of the performed activities. Manager with process management and imple- These deliveries are the process/mile- mentation skills. stones/checklists blended with IX tasks, IX measurement metrics and score cards, and IX design The group can continue doing stage [3] activities patterns or style guides. and storing stage [3] deliveries. In addition, facilitate to blend the IX tasks in the development pro- Follow this in cycles for two-three releases to get cess, and in the involved milestones and check- expertise in this stage. When the top manage- lists. You must productize the new content deliv- ment starts to see the realized value through the eries thus making these recognized and business case studies and ROI statistics, coming

2018 STC Technical Communication Summit Proceedings 127 Sudhir Subudhi

in from multiple projects all around, they would Author Contact Information want to make it a culture in the company and have it all the time, not by force, but by inner Sudhir Subudhi drive. Here you make a smooth transition to the Principal Technical Writer next stage. Oracle India Bangalore +91 7798042299 Stage [5]: Cultured This is the fifth stage into the model. You want Author Biography people across projects to work on better content deliveries and the activities that makes it possible, Sudhir Subudhi has 12+ years of experience in with inner intent and drive, without force. You Technical Writing Services. He is educated with would need involvement, support and guidance of an engineering degree in Information Technology, top management or business stakeholders with and has earned certifications on Management of organizational facilitation, branding, and commu- Software Development and SAFe Agile Practices nication skills. from premier institutions. He is passionate about doing research in the fields of Agile Content, Infor- Continue facilitating stage [4] activities and storing mation Experience, XML DITA, and Content stage [4] deliveries. In addition, now you should through Social Media. work for adoption of IX activities and better content deliveries at board or strategic level. With You can reach Sudhir Subudhi through Linkedin support from top management, ask the team to https://www.linkedin.com/in/sudhirsubudhi/, Email: start sending newsletters featuring IX processes [email protected], and Twitter and value-adds. They can send out communiques @sudhir_subudhi. with words from top leadership on IX. They can run exhibitions, events, and competitions. Ask the team to store or archive the deliveries that come as a result of the performed activities. These deliveries are organizational emails and leadership announcements on IX, newsletters, and exhibitions/events/competitions. Follow this in cycles for 12 months to get the most out of this stage. It’s better to keep doing this in- termittently for perfection and make it a culture to deliver experience through content deliveries.

Resources Geerts, Anneke, de Boer, Jan, and Adriani, Paul. “Game Maturity Model” Compact (2013/4). https://www.compact.nl/en/articles/game- maturity-model/. UX Project Management Certification. http://www.ux-pm.com/.

Artificial Intelligence and Content Val Swisher

Discover how cognitive computing systems are changing the future of content management. I will share with you how cognitive computing systems work, how they learn and how they affect you and me.

When I was at the Intelligent Content Conference How Cognitive Computing Works a few years ago, I had the pleasure of meeting Pavan Arora of IBM Watson. I listened to him The magic of cognitive computing is based on speak about Watson and talk about the enormous natural language processing (NLP). In essence, content opportunity we have in front of us. I found everything that an AI system does is dictated by his talks (both private and public) intriguing and its ability to understand the meaning and intent of inspiring. content. These complex systems read and interpret text like a person. They break down sen- I’ve been in the technology industry for a long tences into components and process the seman- time. I started long before we had a public inter- tics of written material. Once the system under- net. Before cellphones. Before laptop computers. stands the meaning and intent of the text, it can Let’s just say, I’ve seen a lot. However, for the process the information very quickly to draw cor- past decade or so, I haven’t felt a tectonic shift in relations and inferences to potential answers to the way we compute. Sure, smartphones have questions. Most cognitive systems use a broad made remarkable advancements. There are myr- set of linguistic models and NLP algorithms to iad applications that can do everything from make process the data. a simple phone call to turn your lights on and off. In general, though, the way we interact with our devices has remained pretty stagnant. We type How Cognitive Computing Sys- (or speak) things into a computer and it gives us tems Learn the information that it has. We can then ask for To illustrate how cognitive computing systems that information to be presented in different ways. learn, let’s take a look at IBM Watson. Here is We can use keyword searches to see what other what needs to happen in order for IBM Watson to information exists on the web. But, we are asking solve complex problems: for and receiving pretty much the same information that we’ve grown accustomed to since the 1. A large body of content for a particular do- 1990s. main—often called a corpus—is uploaded. Cognitive computing systems represent a true 2. The content is curated by human experts. change in the way we interact with our devices During curation, experts discard infor- and the types of insights those devices serve up. mation that is out of date, immaterial, and Using enormous domain-specific corpora, these deemed to be no good. incredibly powerful systems can analyze data at 3. After curation, the content is ingested. unimaginable speeds. The systems draw infer- When Watson ingests content, it pre-pro- ences, find parallels, and even score multiple, of- cesses the content, creating indices and ten competing results to provide information that a metadata. This makes working with the mere human would not be able to glean perhaps content more efficient in the future. in any amount of time.

129 Val Swisher

4. Once ingested, human experts train Wat- you should be thinking about gathering your cor- son on how to interpret the information. pus, curating it, and creating structured ground This is called Machine Learning. truth pairs to train it. Otherwise, you will miss the 5. During Machine Learning, a human expert boat and your competition will get there before uploads training data in the form of ques- you. tion and answer pairs. These pairs are the If you had told me 30 years that the work I do to- ground truth for the data. day in the field of content would be the key to cog- 6. The question/answer pairs teach Watson nitive computing in the future, I never would have to look for linguistic patterns of meaning in believed you. Yet, here we are at the beginning the domain. Not every question and an- stages of an entire field of computing. All based swer about a topic needs to be uploaded. on linguistics. Instead, by processing the linguistics of the information, Watson learns how to read the information. Watson can then apply this learning to new information as it is Author Contact Information received. Val Swisher 7. After training, Watson continues to learn CEO about a domain from its ongoing interac- Content Rules, Inc. tion with users. Periodically, the interac- 1484 Pollard Road, Suite 255 tions are reviewed by human experts and Los Gatos, CA 95032 fed back into the system. This helps Wat- 408.395.8178 son to better interpret information in the future. Author Biography Remember, it is not the information itself that cognitive systems learn. It is linguistic pattern match- Val helps companies solve complex content prob- ing that allows these systems to locate and score lems. She is a well-known expert in content strat- information. egy, structured authoring, global content, content development, and terminology management. Val believes content should be easy to read, cost-ef- How Does This Affect Me…I Mean fective to create and translate, and efficient to You? manage. Her customers include industry giants such as Google, Cisco, Visa, Facebook, and Veri- On the one hand, the brilliance of cognitive com- zon Wireless. She's the author of three books. puting lies in its ability to find a huge amount of Her latest is Global Content Strategy: A Primer, data in a tiny amount of time. This data can be in an introduction to creating and managing global any form. For example, tweets, articles, blog content. posts, and so on. Once the machine has been trained, the content does not have to be struc- When not working with customers, Val can be tured in order to be found. found sitting behind her sewing machine working on her latest quilt. She also makes a mean hum- But therein lies the rub—in order to train the en- mus. gine, content must be structured. And the structure needs to be very specific. Ground truth is always structured in question/answer pairs. In order for your company to offer services via a cognitive system (whether a chatbot or IBM Watson, or something else), the system must be loaded with content and trained using the ground truth question/answer pairs. Right now, as I type this, the world’s largest and most creative companies are busy training their cognitive systems to answer your questions. If your company wants to stay ahead of the game,

How Tech Writers Will Support SMEs in Writing Technical Content Søren Weimann, DitaExchange

DITA XML has been very successful over the last decade. But it has not always been successful in helping non-technical writers achieve the content reuse and structure that DITA XML implementations were aiming for. A recent survey indicates that the complexity of DITA XML becomes an increasingly bigger problem when implementations spreads wider in the organization. However, technical writers can enable a new approach to content reuse and the tools that allow us to implement structure and reuse with less resistance from the organization.

Since DITA XML became an open standard and The survey included 1/3 from each group with a DITA 1.0 was released in 2005, people have been slight over-representation of those that decided to trying to spread the use of modular and structured drop one or more departments from the imple- content beyond the traditional documentation de- mentation. I tried to find out what was challenging partment. Some have been successful, but many for them. have been hitting a brick wall when they present XML templates and XML tools to Marketing and Development departments. Is DITA XML Too Complex for Time and time again, I myself have presented the Wide Implementations? opportunity of sharing content, reusing topics, The complexity of DITA XML is less of a chal- conrefing legal notes and filtering output for differ- lenge to those that implemented into one depart- ent target audiences. They all see the benefits, ment only. This is not surprising. Ownership alone but more often than not, they take one step back would motivate most people to take on the chal- when they see the tools, the interfaces and ap- lenge. I wanted to know why some implementa- pearance of overwhelming complexity. Some rule tions limited the joys of DITA to include only their it out entirely and some have a hard time finding own part of the organization. 42% of them indi- the available resource to prioritize the change pro- cated that complexity was part of the reason. cess. They did so by saying that other departments Is this really the case all over the world for DITA want to stay in familiar tools, the change process XML? would be too much for them, or plainly that DITA XML is too complex for them (Figure 1). In order to find out, I conducted a survey including 80 companies worldwide. Three types of implementations answered the survey: • Companies that just aimed for implementing DITA XML into one department • Companies that tried to include several departments, but decided to drop one or more of them from the implementation • Companies that implemented DITA XML company-wide

Figure 1: One-department implementations

131 Søren Weimann

Another group of companies tried to implement What if we aim for reducing complexity and then DITA XML into several departments. 70% of these focus on just some of the most important benefits implementations indicated complexity of DITA of DITA XML? XML as part of the reason why some departments Maybe we should limit the reuse and structure cain consideration were not included in the final im- pabilities to: plementation (Figure 2). • Modular content that allows reuse of topics across deliverables • Topic types for task-based writing • Ditaval filtering • Semantic tagging • Con References (conrefs) • Publishing to several formats To reduce the change process and learning curve, we can allow content creators to work in familiar tools that have been adapted to achieve some of the key benefits of DITA XML. On top of this, we want to allow content that is created in those familiar tools to be published in Figure 2: Several-department implementations deliverables alongside DITA XML topics. This way And finally, for those that went all the way and did people who refuse to work in XML can contribute company-wide implementations, 89% saw com- directly to modular and structured content and in- plexity of DITA XML as one of the most significant tegrate their content with departments that enjoy challenges in the implementation (Figure 3). the full suite of DITA XML capabilities. Maybe they can use this chance to become familiar with conrefs, tagging and topics in a familiar tool, and possibly they can use it as a stepping stone before leaping into DITA XML to get the full benefit. Please join my presentation at the STC 2018 Summit to see live demonstrations of how a few technical writers and a content architect can enable: • Hundreds of legal experts around the globe to create structured and reusable content for 50 manuals of local legislation without knowing much more than Mi- crosoft Word • Field agents in an IT company to integrate their own content created in Microsoft Figure 3: Company-wide implementations Word with DITA XML content created by the documentation department DITA XML is complex. That is why DITA XML can do so much. It allows you to manage very complex sets of documentation and minimize risk and inconsistency in an ever-changing world of product development. But if the threshold for more people to benefit from all this is so high that people don’t bother trying or give up before really getting started, then we may need to provide them with a stepping stone.

132 2018 STC Technical Communication Summit Proceedings How Tech Writers Will Support SMEs in Writing Technical Content

Author Contact Information Søren Weimann Implementation Manager DitaExchange Katrinebjerg Science Park Aabogade 15 DK-8200 Aarhus Denmark +45.4029.7560

Author Biography Starting from a master’s degree in pragmatic language theory Søren Weimann has worked his way through world of structured content and component content management—always with a hands-on approach. He led his first DITA XML implementation in 2007 at Motorola Solutions. Since then structured content has been his main focus as a tech writer and information architect in smaller tech start-ups and major Pharma companies. Now he is an implementation manager at Di- taExchange helping customers get up and running with structured content and develop their existing content architecture. He is also a product manager for DxAuthor—an add-in to Microsoft Word that allows content inside Word documents to be tagged and reused in a topic-based deliverable.

The Introvert in the Workplace: Becoming an Influencer and Leader Ben Woelk, Associate Fellow

Many introverts struggle to succeed in the workplace when asked to “think on their feet” or to make decisions without an array of facts in hand. Much workspace design is moving to open plans, where anyone, much less introverts, may struggle with distractions and lack of privacy. Some introverts may look for leadership opportunities, but feel stymied when trying to figure out how to move up. Although not every introvert is interested in a formal leadership position (nor have the opportunity in their workplace), every introvert has the ability to become an influencer.

supporting others so that they can maximize their Influence potential. Influence has been defined in various ways. For the Influence and leadership may not fit traditional mod- purpose of this discussion, we’re referring to influ- els. Influence doesn’t have to depend on your place ence as a verb, having an effect on the character, in the company organizational chart. You may find development, or behavior of someone or something. you have an influence outside of the company as Synonyms for influence include affect, have an im- well. Your influence may occur through mentoring; pact on, impact, determine, guide, control, shape, writing, speaking, or podcasting about a subject govern, decide, change, alter, and transform. Influ- about which you’re passionate. Your influence can ence can be positive or negative. come by being a connector and encouraging collaboration, or encouraging others to develop their Leverage Introvert Strengths and ideas. Abilities Our goal as leaders and influencers should be to have a positive impact on our workplace. Ideally, we Although we’re not all the same, as introverts, we create a culture of safety for our team, where ideas have strengths and abilities that can help us as are freely shared and vulnerability is encouraged. leaders and influencers. Introverted strengths include strong listening skills—the ability to provide reflective listening without just thinking about what Action Plan we’re planning on saying. Introverts often have ana- Read up on introversion and leadership, including lytical skills that help us deeply consider all aspects the article in the May-June 2018 Intercom on this of a problem, weigh the alternatives, and provide a subject that discusses how introverted peers have sound solution. Because we’re not usually driven to become leaders and influencers. Explore MBTI, achieve external recognition, we’re able to partici- Keirsey.com, and other tools that help you uncover pate in a team without seeking a lot of recognition. your strengths and weaknesses and help you understand how you can best excel in the workplace. Influencers and Leaders Engage and network with others. Follow your passion and be sure you take time to recharge. Both in- Not surprisingly, there isn’t one type of influencer or troverts and extroverts can be influencers and lead- leader type that fits all introverts. However, most of ers. You just need to do it in the way that works best us don’t fit the Western image of a strong dynamic for you. leader, nor would we feel comfortable in that role. We’re often comfortable leading from the back,

134 The Introvert in the Workplace: Becoming an Influencer and Leader

Questions to Ponder Author Contact Information • What do I know about myself and my abili- Ben Woelk ties? ISO Program Manager • How will I learn about my abilities? Rochester Institute of Technology 148 Selborne Chase What changes can I make to ensure I’m lev- • Fairport, NY 14450 eraging my abilities to be a positive influ- 585.354.6247 ence in the workplace? [email protected] • How do I ensure I have time to recharge? How can I follow my passion? • Author Biography Ben Woelk, CISSP, CPTC, Associate Fellow, is the 2018-19 STC Vice President. He’s a former Director Resources and Scholarship Committee Chair for STC. Ben Cain, Susan. Quiet: The Power of Introverts in a serves as the Information Security Office Program Manager at the Rochester Institute of Technology, World That Can’t Stop Talking (New York, NY: and is a former Co-Chair of the EDUCAUSE HEISC Crown), 2012. Awareness & Training Working Group. Ben is the Cialdini, Robert. Influence: The Psychology of author of Shockproofing Your Use of Social Media: Persuasion, Revised Edition (New York, NY: Staying Safe Online (Kindle) and served as guest HarperCollins), 2009. editor of the June 2013 Intercom Risk Management Kahnweiler, Jennifer B. The Introverted Leader: issue and the February 2017 Intercom Personality, Building on Your Quiet Strength (Oakland, CA: Temperament, and Technical Communication. Ben Berrett-Koehler Publishers), 2013. provides mentoring for new and emerging leaders Keirsey, David. Please Understand Me II (Delmar, and has created an online Introverted Leadership CA: Prometheus Nemesis Book Company), Community on Slack. 1998. Myers, Isabel Briggs. Gifts Differing. Palo Alto, CA: Consulting Psychologists Press, 1980. Petrilli, Lisa. The Introvert’s Guide to Success in Business and Leadership Kindle e-Book (Chicago, IL: C-Level Strategies), 2011. Woelk, Ben (Guest Ed.). Personality, Temperament, and Technical Communication. Intercom 64.2 (February 2017).

References Coyle, Daniel. The Culture Code: The Secrets of Highly Successful Groups (New York, NY: Bantam), 2018. Woelk, Ben. An Introvert’s Journey to Leadership (Proceedings, STC Summit Conference, 2016). Woelk, Ben. “The Introvert in the Workplace: Becoming an Influencer and Leader.” Intercom: 65.3 (May-June 2018).

2018 STC Technical Communication Summit Proceedings 135