Writing Rapidly and Establishing Standards in Web Software Documentation
Total Page：16
File Type：pdf, Size：1020Kb
ABSTRACT WORKING AS AN AGENT OF CHANGE: WRITING RAPIDLY AND ESTABLISHING STANDARDS IN WEB SOFTWARE DOCUMENTATION by Sarah Elizabeth Burke This report discusses my internship experiences at Fig Leaf Software in Washington, DC, where I worked as a technical writer during the summer of 2001. In the report, I describe the young, rapid-development environment in which I worked, my major tasks and projects, and a significant project that I completed during my internship. During this project, I faced many challenges in developing the company’s first client installation guide, including staying within the allotted hours and budget, gaining access to technical information, and establishing standards for a new document type. After discussing these challenges, I examine my role and value as an agent of change at Fig Leaf Software and present an expanded organizational role for technical communication practitioners. WORKING AS AN AGENT OF CHANGE: WRITING RAPIDLY AND ESTABLISHING STANDARDS IN WEB SOFTWARE DOCUMENTATION An Internship Submitted to the Faculty of Miami University in partial fulfillment of the requirements for the degree of Master of Technical and Scientific Communication Department of English by Sarah Elizabeth Burke Miami University Oxford, Ohio 2003 Advisor ________________________________ Dr. Katherine T. Durack Reader ________________________________ Susan E. Gertz Reader ________________________________ Dr. Jean A. Lutz Reader ________________________________ Dr. LuMing R. Mao © Sarah Elizabeth Burke 2003 Contents Chapter 1: Introduction........................................................................................................ 1 Fig Leaf’s History, Organization, and Culture..................................................................................1 About the Technical Writing Team.....................................................................................................3 Chapter 2: Diverse Projects, Common Solutions ............................................................. 5 Two Significant Projects .......................................................................................................................6 Project 1: Compose Specification Process Guide.....................................................................6 Project 2: Create Instructional Text for an Application ..........................................................8 Common Solutions..............................................................................................................................11 Chapter 3: Standard-Setting Project: Developing a Client Installation Guide............. 13 Overview and Phases of the FLS Documentation Process ............................................................13 Phase 1: Planning.......................................................................................................................14 Phase 2: Development...............................................................................................................16 Phase 3: Review .........................................................................................................................16 Phase 4: Delivery .......................................................................................................................20 Evaluation of the Project ....................................................................................................................20 Chapter 4: My Role and Value as an Agent of Change................................................... 22 My Role as an Agent of Change........................................................................................................22 Candidate for Change: The FLS Documentation Process..............................................................23 The Organizational Value of My Role as an Agent of Change .....................................................25 References .......................................................................................................................... 28 Endnotes ............................................................................................................................. 29 Appendix A: Fig Leaf Technical Writer Skill Set Requirements.................................... 30 Appendix B: Introduction from Specification Process Guide ....................................... 35 Appendix C: Fig Leaf Software Documentation Process............................................... 38 Appendix D: Original Installation Steps for Client Installation Guide .......................... 41 Appendix E: Final Client Installation Guide..................................................................... 44 iii Chapter 1: Introduction Vibrant chartreuse and plum walls, a flat screen monitor pumping out eye-catching multimedia spots, and unfamiliar acronyms, words, and phrases like CFUG, ColdFusion, and “Rock the Fig” greeted me in my life as a technical writer at Fig Leaf Software (FLS) in Washington, DC.1 I began full-time work for this small, yet dynamic, software company on April 9, 2001, and completed my internship for the Master of Technical and Scientific Communication (MTSC) degree at Miami University from May 21, 2001, to September 7, 2001. When I began working for Fig Leaf in its cutting-edge office space, I did not expect to gain more than industry experience in creating software documentation. However, working in a young, rapid-development environment that was light on standards and heavy on politics taught me far more. During my employment and internship at FLS, I discovered that educating coworkers about my profession, establishing standards and processes, and negotiating organizational change were crucial to developing software documentation in this organization. More importantly, I learned that these skills, which I had considered outside of technical communication, were an integral, everyday part of practicing technical communication in the “real world.” The main purpose of this chapter is to describe the history, organization, and culture of the company in which I worked and to explain how the corporate culture shaped the work environment at FLS. I also discuss the roles and goals of the Technical Writing team and the challenges I faced as a technical writer working in this new department and within a unique corporate environment. Fig Leaf’s History, Organization, and Culture Fig Leaf Software’s youth and reputation as a champion of technology permeates its history, organization, and corporate culture. Steve Drucker and Dave Watts founded Fig Leaf Software in 1992 as a custom software development firm specializing in desktop database applications. To take advantage of emerging technologies, FLS shifted its focus in 1995 to “Web-centric applications, data-driven Internet sites, and creative media” (Fig Leaf Software, n.d., n.p.). Its service offerings shifted as well and now include the following: software consulting, creative and interactive media, software training, and software product sales. At the time of my internship, FLS employed roughly 65 people in both the Washington, DC, corporate headquarters and at the Atlanta, GA, satellite office who together developed custom Web solutions for Fortune 1000 organizations, trade associations, and government agencies. Most of this development was completed using advanced technologies like Macromedia ColdFusion® and Macromedia Flash®. 1 The organization of FLS also reflected its youth as a company and its strong focus on technology. To stay abreast of rapid technological changes in the Internet and interactive media industries and meet the distinct needs of its clients, FLS operated like a matrix organization. It overlaid its fairly rigid organizational structure, organized departmentally by service offering (see Figure 1), with a more fluid project-team structure. On a project basis, FLS formed ad hoc teams from various departments that were more able to adapt to the unique demands of each client and project. Moreover, Fig Leaf’s Chief Technology Officer position and its executive placement in the organization revealed not only FLS’s love of technology but also its desire to put technology first. President and CEO Chief Chief Vice President Vice President Vice President Director of Technology Financial of Consulting of Sales and of Creative Project Officer Officer Services Marketing Services Management Human Creative Project Administration Training Staff Accounting Staff Resources Proposal Writer Recruiter Services Team Management Support Staff Staff Leads Staff Quality Technical Development Creative Assurance Writing Team Team Lead Services Staff Team Lead Lead Development Quality Technical Staff Assurance Staff Writing Staff Figure 1. Fig Leaf Software's organizational structure Similarly, Fig Leaf’s corporate culture demonstrated its youth as an organization and portrayed its image as a trendsetting, technology pioneer. Its office space provided some of the most distinctive examples of this corporate culture. For example, the ultra modern conference room with its chic industrial lighting, flashy marketing banners, and trendy Herman Miller® office chairs conveyed a cutting-edge, image-conscious culture. In addition to trendy and cutting edge, Fig Leaf fostered a culture that was both “fun” and “homey.” The toys strewn across employees’ desks, the personal stereos peeking from corners, and the company games room— complete with pool table, television, and punching bag—captured Fig Leaf’s culture of fun. Open