Structuring Your Documents to Maximize Reuse

Transcription

1 A Publication of The Center for Information-Development Management Structuring Your Documents to Maximize Reuse Janice (Ginny) Redish Single Sourcing Requir uires es Structur uctured ed Documents A major topic among information development managers these days is single sourcing writing information once and using it many times. Structured documents are critical for single sourcing. So, let s explore what we mean by structuring documents why structuring is useful some of the concerns that writers have about structuring documents Note: Even if you aren t yet considering single sourcing, you ll find that structuring documents is an extremely useful, time-saving technique. It works in traditional publishing and is useful for individual writers in any situation where they have to create the same type of document many times. It is essential for teams of writers who are contributing parts to a large document or to a set of documents. Wha hat t Do We e Mean by y Structur ucturing ing Documents? s? Structuring documents is a process that involves several steps: listing all the different information elements that a particular type of document might have naming the information elements setting the guidelines for organizing documents deciding which information elements may (or should) appear in a particular type of document and in what order Why is a consistent look and feel important? It s good for the company because it promotes an image of competency. setting style standards for each information element linking the named information elements to templates, specifying how a document will look on paper or on the screen Listing the information elements We all use a variety of information elements in our documents. A document might have a title; headings at various levels; different types of text, including introductory paragraphs, procedural steps in numbered lists, tips, hints, notes, and examples; different types of graphics, such as icons, screen shots, and technical illustrations; captions and callouts for those graphics; and so on. Pick up any document that you work on and identify the different information elements that make up a typical page of that document. Figure 1 on page 43 shows an example of the information elements on a page of a print document. Naming the information elements To make structuring work, each information element must have its own name so that it is listed separately in templates and style sheets. An important issue to consider is the level of granularity that you need. Is a general name for a type of text sufficient? Or should you name the information elements by the specific content that they convey? For example, for most of this article, I The Center for Information-Development Management 710 Kipling Street Suite 400 Denver, CO Continued on page 43 JUNE 2000 VOLUME 2, NUMBER 3 Contents Structuring Your Documents to Maximize Reuse page 41 From the Director page 42 CASE STUDY Controlled English as a Way of Standardizing Content page 48 What Do the AECMA Guidelines Say? page 52 TOOLS AND TECHNOLOGY POET Content Management Suite page 54 MANAGING 101 Understanding Your Style page 56 Manager s Calendar page 57 IN PRINT page 58 TALK BACK Responses to April s Question page 60 41

2 FROM THE DIRECTOR Best Practices Newslet wsletter ter A publication of the Center for Information-Development Management. 710 Kipling Street, Suite 400 Denver, CO Phone: 303/ Fax: 303/ best.practices@ infomanagementcenter.com Publisher and Center Direct ector JoAnn Hackos, PhD joann.hackos@comtech-serv.com Managing Editor Katherine Brennan Murphy best.practices@ infomanagementcenter.com Production Manager Lori Maberry lori.maberry@comtech-serv.com How to subscribe: a one-year subscription (6 issues) is $99. Subscribers outside the US add $10 (US funds only). Contact Marilyn Slifka at 303/ , or send to best.practices@infomanagementcenter.com How to submit an article: contact Katherine Brennan Murphy best.practices@infomanagementcenter.com How to join the Center: call JoAnn Hackos at 303/ , or send to joann.hackos@comtech-serv.com 2000 Comtech Services, Inc. All rights reserved. Printed in the USA From the Director JoAnn Hackos Dear Friends and Colleagues Some call it a curse May you live in interesting times. If it is a curse, we are all well cursed because these are certainly interesting times for information-development and training managers. Just when we have more to do than ever before and are expected to do more in less time than ever what do we discover? An employment environment that challenges us to find talented people to hire and maintain our staff in the face of stiff competition from other managers. How do we cope? What are the tactics that work? What are the pitfalls we need to avoid? I am looking for a solid group of managers and organizations who want to tackle these questions together. We are now actively recruiting you to join in the Staff Resources Benchmark Study. By now, you have received project descriptions and even calls from the staff and me. My goal is to recruit 12 organizations to help build the body of knowledge and experience that will make us all more successful. Over the years, I ve pursued many alternative approaches to attracting and nurturing qualified staff. For some period, we actively recruited at academic institutions. We found talented young people willing to learn about a field really new to them. We looked for graduates who demonstrated an interest in technical subjects and a commitment to effective writing. Sometimes that meant finding the rare student who double majored in physics and English. Or the math major who wrote for the college newspaper. Or the technical communication master s graduate with an undergraduate engineering degree. We found we could train them in our methodology and keep them for two or three years. Unfortunately, many of these promising young people decided that they really wanted to pursue their careers elsewhere few stayed in technical communication. They went on to marketing, management, even massage therapy. I m sure they did well, but technical communication proved not strong enough to sustain their interest. I ve often wondered why. We know, for example, that most of the 20 to 25 percent of STC members who fail to renew their memberships each year move on to other fields. Most attendees at STC conferences have been in the field for two years or less. Why the volatility? Are we, in fact, different from any other field that does not require certification for entry? From my days in engineering education, I know that engineers who have spent four years in undergraduate engineering often leave the field after three to four years. Many go on to management positions, but others decide to do something different. When our sons were in college, my husband and I counseled them to take a variety of courses, especially those taught by talented faculty members. An eclectic education, we argued, would serve them best because they were likely to change careers several times. So far, they re still in the careers they first chose biophysics and international finance. What do we, as senior managers and longtimers, do to keep talented people in the field? How do we create a compelling and fulfilling work environment? Do we offer higher salaries? Do we let them work at home? Or bring their dogs to the office? How do we make the work itself more interesting and challenging? As we prepare for the Second Annual Best Practices conference in early October, we will focus on the results of our Staff Resources Benchmark Study. We plan to report on solutions and challenges that the benchmark partners discover. If you want to be a member of this ground-breaking group, please contact me today. JoAnn 42 JUNE 2000 BEST PRACTICES

3 STRUCTURING YOUR DOCUMENTS Continued from page 41 like body text and bulleted list. Body text is any prose paragraph no matter what the content. Bulleted list is any list (other than one with numbers) no matter what the content. However, I decided that I wanted the names of the styles (that is, body text and bulleted list) to be set in a different font from typical body text paragraphs. So, now I have another information element, name of style. I keep it separate from body text as an element of my document so that I can set and change the formatting for it differently from other parts of the document. In single sourcing, where you are developing a content-management system, you may want to separate and name elements by content, even if they have similar formatting in most documents. Information elements that you want as separate entities might be as small as a few words, such as the name of the company. The advantage is that if the name changes or the font in which the name must be used changes, you can change that in all your documents without disturbing any other part of the document. Setting guidelines for organizing documents One of the main advantages of structuring documents is that it promotes consistency in formatting in the way the document looks on paper or screen. We ll get to that advantage in a later section. Another advantage is that, through the process of structuring documents, you can also promote consistency in both organization and style. As information development managers, you know that documents must be carefully planned. You expect writers to organize and outline their documents. When you work within the process of structuring documents, you add questions like these to the organization phase: What information elements are relevant to this type of document? What purpose does each information element serve in this type of document? What arrangements (organizations, sequences) of information elements are best for users of this type of document? For example, the document in Figure 1 is the setup manual for a personal computer system. When we planned this manual, we realized that the critical information elements were exactly the ones you see in Figure 1: Center Associates Judy Glick-Smith Integrated Documentation, Inc. judy@idoc-inc.com Henry Korman WordPlay Communications korman@wp-consulting.com Katherine Brennan Murphy Tapestry Communications tapestry@spiritone.com Ginny Redish, PhD Redish & Associates, Inc. redish@ari.net Ann Rockley The Rockley Group rockley@rockley.com Advisor visory Council Julie Bradbury Cadence Design Systems julieb@cadence.com Diane Davis Synopsys ddavis@synopsys.com Marit Johansson Ericsson Radio Systems AB marit.johansson@era.ericsson.se Mike Lewis NCR michael.lewis@sandiegoca.ncr.com Gil Mounsey NCR gil.mounsey@ncr.com Robin Reddick BMC Software robin_reddick@bmc.com Deborah Rosenquist Dell Computers deborah_rosenquist@dell.com Figur igure 1: Informa mation elements s on a page BEST PRACTICES JUNE

4 STRUCTURING YOUR DOCUMENTS am working with typical style sheet elements the task a brief introduction to the task steps for completing the task a graphic (or graphics) to illustrate the component and relevant actions a footer with book title and page number Other information elements, such as operating procedures, conceptual information, rationales, and so on, were not relevant to this type of document (given the goal of helping users get set up and running in a very short time). The order in which the information elements appear is structured to match the user s logic. Every section of this manual has these four elements in this order with the provision that steps and graphics may be interspersed if a graphic is needed for a step part way through the procedure. (That s what you see here. Step 3 with another graphic is in Figure 2.) In other documents, different parts of the document might have different information elements to match their different functions, but similar parts of similar documents should be organized in the same way. Structuring helps to achieve this level of consistency and patterning, which in turn helps both writers and users. Setting style standards for each information element It also helps both writers and users to have consistency in the style for writing each type of information element. Figure 2 shows our example with style standards for some of the information elements. Ironically, the automatic structuring tools that we have (style sheets in word processors, templates and document definitions in content-management systems) are all about formatting, not about writing style. For writing, we must rely on publishing and distributing standards and style guides, training writers, and having good editors. Don t neglect this aspect of structuring documents, however. Good style standards for each information element are critical. Linking the named information elements to templates One of the main goals of structuring documents is to have all the exemplars of a given Figur igure 2: Order of elements 44 JUNE 2000 BEST PRACTICES

5 STRUCTURING YOUR DOCUMENTS document type look alike. Once you have structuring in place, writers construct documents by using the organization guidelines, style standards, and template and by assigning everything in the document to the appropriate type of information element. Therefore, the writers can concentrate on the content without worrying about the format. Another goal of structuring documents is to reuse content. That might mean taking one chunk of content (for example, a paragraph, list, or graphic with caption) and using it in several documents. It might mean taking an entire document and publishing it in different media with formats that are appropriate to each medium. Why Is Structur ucturing Useful? The bottom line for most companies is that structured documents save money. They also make life easier both for writers and for users. Here are some of the benefits: Writers can focus on users and content rather than fussing endlessly about page layout or having to remember how they formatted a similar piece or an earlier part of the same document. Writers are more productive. There s less rework. Writers can borrow content from each other or from themselves. There s less redundancy and chance of errors in the content. Editors can concentrate on high-level issues because consistency of formatting is assured. If writers follow guidelines for organization and style, editors need to do much less to achieve consistency within and across documents in those areas, too. They can focus on overall usability, relevance, accuracy, and coherence. Reviewers save time. When content is reused, it may not need to be reviewed each time. Writers or product specialists are much more productive at the end of the process. There is much less need to go in and fix it up to look like it should. Note, however, that the need for production specialists and clean-up time doesn t disappear entirely. Some tweaking to make information fit on a page or screen, to keep relevant content together, to make pages or screens both usable and aesthetically pleasing is still needed. None of the available tools does a perfect job of conversion from one software package to another. Reviewing the formatted version of output files is still a necessity. Writers can easily change the format of a document. Consistency is maintained when the document is changed. Users get documents with a consistent look and feel. Why is a consistent look and feel important? It s good for the company because it promotes an image of competency. It s also good for users. People are pattern-oriented. We see patterns even where they don t exist, and we quickly build expectations from what we see. Inconsistency in formatting leads us to wonder why something is different, and that takes time away from dealing with the content. It is easier to grab information quickly from a document when we know where to look for whatever we are looking for. To achieve these benefits, however, you have to have documents that are well-structured, and writers and editors have to use the templates and style guides. It takes time and resources to set up a carefully structured document and to train writers and editors, but the initial investment will be repaid rapidly in savings on each later document. (See the sidebar on how to set up structured documents.) Wha hat t Concerns ns Might Writers Have About Structur ucturing ing Documents? s? I ll consider three questions that writers often have about a move to structured documents: Doesn t structuring stifle creativity? I m the only one who writes this type of document. Why should I think about structuring it? I m working on the Web. What s the relevance? Doesn t structuring stifle creativity? No! In fact, structuring frees writers to con- To contact Ginny, call or send to Ginny Redish, President Redish & Associates, Inc Winterberry Lane Bethesda, MD / Redish@ari.net BEST PRACTICES JUNE

6 STRUCTURING YOUR DOCUMENTS centrate on the parts of the process that they often wish they had more time for. They can pay more attention to meeting users needs and to the information itself. They must still do audience and task analyses. Even if an overall organization and style is set for a type of document, they must still decide what information to include and what words to use to convey that information. And if they spend less time on writing and page layout, they might have more time to sit with users before writing and to do usability evaluations with users when they have a draft. Writers and editors should be involved in the process of structuring the documents they work on in deciding on appropriate information elements, on guidelines for organization and style, and on the templates. In fact, to develop good documents, you might want to include the skills of information architects, document designers, typographers, and usability specialists, as well as writers, editors, and users. In my experience, although writers have sometimes expressed this concern about creativity before a project to structure documents, when the structuring is in place, they are thrilled. They quickly see that working with structured documents is liberating; it makes their work much easier. I m the only one who writes this type of document. Why should I think about structuring it? Structure is valuable even for single authors. Why spend time creating the format each time you write a letter or a memo or send a bill or an invoice? Word processors make it easy to create templates based on a sample document. Consistency in the format of your documents makes you look good to clients and users. For example, if you send an invoice to the same client every month, you save both In my experience, although writers have sometimes expressed this concern about creativity before a project to structure documents, when the structuring is in place, they are thrilled. They quickly see that working with structured documents is liberating; it makes their work much easier. yourself and the client time and effort if you use a template. Moreover, a template can help you remember what information you have to include. I m working on the Web. What s the relevance? One secret of successful Web sites is Web pages with clear structure. Part of the analysis phase in planning a Web site should include these stages: identifying all the information types to include on the site grouping them into types of pages (for example, on an e- commerce site, you will have list pages, item description pages, fill-in form pages, and so on) developing an organization, style, and template for each of those page types Several people may be involved in writing, editing, and producing pages to get a Web site up or updated in what always feels like impossible deadlines. Working with structured pages saves tremendous amounts of time while providing the consistency that makes the site look good and work well for users. For further reading Glick-Smith, Judy, 1999, How to Successfully Implement Document Management, in Best Practices, vol. 1, Redish, J. C., 1999, Document and information design, in J. G. Webster (Ed.), Wiley Encyclope- Engineer- dia of Electrical and Electronics ing, NY: John Wiley & Sons, vol. 6, Rockley, Ann, 1999, Single Sourcing, in Best Practices, vol. 1, Schriver, K. A., 1997, Dynamics in Document Design: Creating Text for Readers, NY: John Wiley & Sons. Weiss, E. H., 1991, How to Write Usable User Documentation, Phoenix, AZ: Oryx Press. 46 JUNE 2000 BEST PRACTICES

7 STRUCTURING YOUR DOCUMENTS The process for setting ting up structur uctured documents You want not just structured documents but ones with structures that work for both writers and users. How do you do that? Here are steps to take and questions to answer: 1. Understand the big picture Analyze your documents What types of documents do you have now? What other types will you need in the future? What overlap is there among these documents? How often do these documents change? How accurate and usable are these documents now? Understand the users and their needs Who needs what information? Do these people use the documents? If not, why not? Is the information distributed appropriately among the current types of documents? 2. Analyze each document type For each document type: Collect several examples that work for users. List all the types of information elements in them. Do users need all those elements? Are there other information elements that users need? Organize the elements into useful sequences. Plan appropriate styles for each information element. Design pages or screens to present the information clearly. Create a template and style guide for the elements. Develop a draft model document using the template and style guide and do usability testing with users. Make sure you have a model document that works for its users before you institutionalize its structure! 3. Understand writers, editors, and reviewers What skills and experience do your writers have? What will it take to help them learn and use templates, style guides, and new systems easily? What process do they now use to develop documents? What process changes are needed to help them accept and develop reusable, structured documents? How do reviewers fit into the current process? How will they fit into the new process? What will it take to get them to support and work in a new process? BEST PRACTICES JUNE

8 CASE STUDY CASE STUDY Controlled English as a Way of Standardizing Content Katherine Brennan Murphy, Center Associate In this issue s feature article, Ginny Redish discusses ways of structuring documents to facilitate single sourcing. Organizations who employ a Controlled English standard also reap benefits when moving to single sourcing. This case study offers success stories from Caterpillar Tractor and Boeing and the lessons we learned at Tektronix when we proposed developing work instructions using Controlled English. Back ckgr ground After World War II, manufacturers of large equipment found that they needed to provide maintenance manuals to service centers in countries where English was not the primary language. For the Caterpillar company, the equipment they produce is often still found working in almost any country in the world 50 years after it was built. As for Boeing, airplanes must be serviced at specific intervals to meet certification requirements. At least half of the maintenance personnel who work for airlines around the world do not read English. Maintenance manuals for airplanes are many thousands of pages long. By international agreement, translation into other languages is not required, so Boeing writes the maintenance manuals in English. In fact, if aerospace manufacturers translate the manuals, they are liable for the accuracy of the translations. In the aerospace industry, mistakes caused by faulty translations can be life threatening. With the Esperanto movement as a precedent, linguists and writers began considering the idea that perhaps a subset of English could be developed and then taught to maintenance personnel around the world. This subset would have strict grammar rules and a very carefully controlled vocabulary. Out of these early attempts, Controlled English language standards have developed. Caterpill terpillar Caterpillar Tractor Corporation was one of the earliest corporations to develop and teach a form of Controlled English, called Caterpillar Fundamental English. They wrote documents in Caterpillar Fundamental English and taught non-english readers at their regional service centers how to read and comprehend this form of English. It took 1 to 1½ years for the technicians to be trained, and Caterpillar often had to find people who were willing to go to remote areas as trainers. However, with a stable, well-paid workforce, this process met the needs of maintenance in areas where the Roman character set is used. As Caterpillar expanded its global market, several problems arose. Often the people being trained were not Caterpillar employees, and once they learned some English, they left for other jobs. Also, it was harder to find people willing to go to remote or dangerous areas to train others. Finally, when working in cultures whose native character set was other than Roman, Caterpillar first had to teach an entirely new alphabet as well as a new language. Over time, the investment, both in writing and teaching, became too costly to maintain. Caterpillar created writing guidelines for all English manuals to facilitate translation and relied on the competence and diligence of its writers and editors to use standard grammar and vocabulary. Given the enormous number of pages produced and the fact that engineers wrote the procedures, this ad hoc process broke down over time. The final demise of Caterpillar Fundamental English was the rapidly increasing complexity of the equipment, especially the electronics and advanced engine controls. The extremely small and simple vocabulary was clearly insufficient. In the mid 1980s, Caterpillar began automating the documentation process, moving the documents onto computers and beginning to look at machine translation. However, efficient and accurate machine translation requires that the input vocabulary and sentence structure be unambiguous. This requirement can be difficult to achieve when 48 JUNE 2000 BEST PRACTICES

9 CASE STUDY more than 180 authors are contributing to the manuals. Caterpillar also began planning to create documents using information elements so that text could be stored, reused, and modified in one place. To meet these requirements, they worked with the Language Technologies Institute (LTI) at Carnegie Mellon University to develop an authoring tool that assists authors to follow the writing guidelines and use standardized vocabulary. This tool internally diagrams each sentence the author writes and provides information on how the sentence may not meet the standards. This tool has made four contributions to the authoring process: Provides authors with immediate feedback on documents as they write, which allows the tool to be, in effect, a training aid Creates a process to maintain a standard vocabulary, while adding and deleting words, which facilitates machine translation Enables the single-sourcing process Improves productivity and accuracy through text reuse Eric J. Adolphson manages the group at Caterpillar that maintains the language integrity of this system. Adolphson has completed advanced post-graduate work in Computational Linguistics and, with two other writing professionals, specifies to the authoring system how to apply the rules. This group also screens requests from authors to add new words to the master dictionary. Each word must have a clear definition that removes ambiguity. Over 1,000,000 words are processed by the authoring system each week. Of these, 60 new terms are added to the dictionary. Caterpillar s maintenance systems are highly automated, allowing the day-to-day maintenance of a complex, controlled-language application to be performed by three people. Development of the system and the machine translation components is performed at LTI. At Caterpillar, authors have engineering backgrounds; they are hired primarily for their technical expertise rather than their writing skills. The authoring system helps create unified documentation that can be easily translated into native languages. Because Adolphson s staff is available for consultation, the rules and vocabulary do not stagnate. The authors do sometimes chafe at the restrictions, saying That s what they call it in the field. or That s what the engineers call it. However, the system does ensure that these 180 writers consistently follow rules and use the same terminology throughout. Adolphson also points out that standardization results in documents without much tone, especially in English because English has the largest vocabulary of any language. The repetitive vocabulary combined with a standard sentence style makes for bland sounding prose, which is not inappropriate for technical documentation. He also says that, sadly, authoring tools are replacing human editing. However, by following the guidelines and using the authoring tool s suggestions, technical writers can learn to be better at their craft. For example, the authoring tool requires that no noun phrase be longer than three words unless it is the name of a part. Recasting these noun stacks requires considerable skill on the writer s part. Boeing The aircraft industry s experience is similar to Caterpillar s. Their motivation, though, was to fulfill stated customers needs. At least half of the maintenance workers of airline companies do not have English as their native language. The airlines they work for demand maintenance manuals that their employees can easily comprehend. Fokker Aircraft began the Simplified English movement in the aircraft industry in the 1970s. In 1982, the Association Eurpeene des Constructeurs de Materiel Aerospatial (AECMA) and the Aerospace Industries Association (AIA), following Fokker s lead, jointly developed an international standard that aircraft manufacturers and airline companies could use as a baseline (Gingras 1987, 25). The AECMA Simplified English standard, released in 1986, outlines style and grammar rules and lists both allowed and proscribed vocabulary. Boeing, in cooperation with 17 other companies, worked to create the standard. (See the summary of the AECMA standard on page 52.) Boeing found the same issues as Caterpillar did when implementing the standard in BEST PRACTICES JUNE

10 CASE STUDY References ences Calistro, Ralph E., 1993, Simplified English Roundup: Fait Accompli or Impossible Dream? Proceedings of the Society for Technical Communication Annual Conference, pages Gingras, Becky., 1987, Simplified English in Maintenance Manuals, Technical Communication, First Quarter, pages The European Association of Aerospace Industries (AEC- MA), 1998, AECMA Simplified English: A Guide for the Preparation of Aircraft Maintenance Documentation in the International Aerospace Maintenance Language. Issue 1, Revision 1. Spryidakis, Jan. Personal communication. house writing in Simplified English is extremely difficult without authoring support. Writing good Simplified English requires a massive learning curve; most of the writers are engineers who are hired for their technical competence not just their writing skills. They need to be domain specialists. Boeing s Natural Language Processing group, managed by Jim Hoard, developed an authoring support tool called the Boeing Simplified English Checker. In production use since 1990, the checker is still maintained by the Natural Language Processing group. Jim has a PhD in Linguistics and many years of experience with Boeing. His staff includes both linguists and computer scientists. Over 1,000 authors use this tool. The Boeing Simplified English Checker runs on top of authoring tools (including Adept and Microsoft Word). There is also a Web-based interface. The authors submit their text to the checker, and they receive feedback on violations of the Simplified English writing rules and vocabulary restrictions. Authors attend a short class where they learn about the philosophy and goals of Simplified English. All of their training comes from using the tool. There is still a steep learning curve, but it is lessened by using a convenient, interactive authoring tool. Even though Boeing implemented this solution in response to customer needs, they have reaped additional internal benefits. First, they were able to gain consensus across product lines on technical terms. Second, their document management system uses the information elements to assemble manuals that are customized to a particular airline customer. Third, when the need arises for documents to be translated (for example, internal procedures at Boeing or marketing materials), the controlled vocabulary facilitates this process. Fourth, they have been able to turn this effort into a saleable product. Tektr ektronix One of my professors in graduate school, Dr. Jan Spyridakis, had worked with Boeing on evaluating the comprehension of Simplified English texts. When I was faced with the task of trying to upgrade over 3,000 work instruction documents at Tektronix, I remembered the research Spyridakis had done. After looking through articles and talking with several contacts, I proposed that we consider implementing a variation of Simplified English for our process documents. To be usable, the system needed to accommodate the following parameters: A stable workforce, a significant percentage of whom read English as a second language An extensive work instruction library (more than 3,000) documenting 1,700 products with 8,000 options, with each document being revised (on average) every two months A move to a more highly automated and customized manufacturing environment A quality system that required manufacturing engineers to author work instructions A move to online work instructions We started our investigation by purchasing the AECMA standard and working on a vocabulary that was suitable for our manufacturing domain. I taught a four-week class for Manufacturing Engineers to give them an idea of what would be involved in such a process. My team also created some prototype online work instructions using Simplified English guidelines. I left Tektronix not long after this project moved into the feasibility stage. However, the first order of business was to purchase authoring software or build it in house. We considered the software to be the most important ingredient because, as at Caterpillar and Boeing, our authors were engineers. Ultimately, Tektronix decided not to pursue a Controlled English option. First, Tektronix went through a significant restructuring in 1999 and, as a result, did not have the resources to work on this project. Second, after I left, there were no information developers working in Manufacturing. Third, the Manufacturing Engineers decided that the rules and vocabulary would be too confining. Fourth, the system they had in place was adequate for now. Conclusions The experience of Caterpillar and Boeing shows that producing documents that conform to a Controlled English standard has 50 JUNE 2000 BEST PRACTICES

11 SINGLESOURCE CONFERENCE definite benefits both to the company and to the end users. Both Caterpillar English and Boeing Simplified English resulted in higher quality documents and lower costs to translate technical manuals. However, their experience, particularly Caterpillar s, points out that without the authoring support tools, the cost is too high. This authoring support solves both the consistency and training problems that organizations can encounter when implementing such a system. When supported by an interactive tool, technical authors can focus on content issues rather than style and word choice. In both of these successful implementations, there were overwhelming customer or internal requirements driving the move to Controlled English. My experience at Tektronix points out that without an overwhelming corporate need translation, single sourcing, regulator requirements, customer needs, or tens of thousands of pages the move to a Controlled English standard may be difficult to accomplish. This experience also reminds us of the importance of involving a consistent, strategic leader who can manage up and sideways as needed. Both Eric Adolphson and Jim Hoard provide this strategic leadership in their companies. If you are interested in learning more about their success stories or how you could apply their experience to your problems, please send them . For more information, contact Jim Hoard Jim.Hoard@PSS.Boeing.com or Eric Adolphson adolpej@cat.com A two-day follow-up to last year s SOLD OUT Single Source Summit. The conference hotel is located in Chicago s northwest business corridor, just 20 minutes from downtown. SingleSource 2000, brought to you by the Center for Information-Development Management and SingleSource Associates, will bring together documentation professionals to explore strategies and solutions for reusing and multipurposing information. SingleSource ce 2000 Back by popular demand! July 31 and August 1, Wyndham Northw thwest Chicago Hotel You ll hear from speakers who have successfully implemented single sourcing in their organizations, and vendors who will demonstrate their publishing tools and answer your questions. For more information, check out <singlesource2000.com>, where program and registration details are posted. You may also contact our conference coordinator, Julie Price, at (303) or her at julie.price@comtech-serv.com. BEST PRACTICES JUNE

12 AECMA GUIDELINES What Do the AECMA Guidelines Say? Katherine Brennan Murphy, Center Associate In the General Introduction to the AECMA Guidelines, the authors explain the need for simplified English: Even though English is more and more the international language of aerospace, certain facts must be faced: English has many forms depending on the nationality (or region of that nationality) And even the purest English, with all regional dialect or jargon removed, can be difficult to understand if the grammar or word usage is too complicated. They go on to describe AECMA Simplified English as a controlled general vocabulary and a set of writing rules. Vocab ocabul ular ary Guidelines In addition to the basic words in the vocabulary, each organization adds what are called Technical Nouns or Manufacturing Processes that are unique and well defined within that organization. Each vocabulary entry lists the word and its required part of speech. It also states whether the word is allowed or not and what substitutions are acceptable if the word is disallowed. For example, the word test is approved as a noun but not as a verb. After the entry for test, you learn the following: BEFORE: Test the system for leaks AFTER: Do the leak test for the system. OR: Do a test for leaks in the system. The writer must also use the approved meaning for a word. For example, the word follow means come after rather than obey. BEFORE: Follow the safety instructions AFTER: Obey the safety instructions The standard also restricts the forms of verbs and adjectives. For example, a writer must not use the ing (progressive) form of verbs. After looking at these few examples, you can immediately appreciate the difficult task of compiling a dictionary for an organization. Style yle Guidelines The style guidelines are more in tune with what any experienced technical writer would expect. Even so, following them can be a difficult process. Here are the major style rules: Make your instructions as specific as possible. BEFORE: Different temperatures will change the cure time. AFTER: Increase the temperature to decrease the cure time. Do not use noun clusters of more than three nouns. BEFORE: The nose landing gear uplock bolt is AFTER: The bolt that attaches the uplock to the nose landing gear is. Use an article or a demonstrative adjective (this, these) before a noun. BEFORE: Lift up assembly and put in box. AFTER: Lift up the assembly and put it in a box. Use only infinitive, imperative, simple present, simple past, and future verb forms. Use only the active voice in procedural writing and as much as possible in descriptive writing. Keep to one topic per sentence. Do not omit words to make your sentences shorter. 52 JUNE 2000 BEST PRACTICES

13 AECMA GUIDELINES Use a tabular layout for complex texts. Use connecting words to join consecutive sentences that contain related thoughts. Keep procedural sentences as short as possible (20 words). Write only one instruction per sentence and use the imperative. Write more than only one instruction per sentence only when more than one action is done at the same time. Examples from om Caterpill terpillar ar BEFORE: Clean the element and cover. AFTER: Clean the element and the cover. OR: Clean the element and cover the element. BEFORE: Take a measurement of the clearance. AFTER: Measure the clearance. BEFORE: Do the parking brake efficiency test. AFTER: Test the efficiency of the parking brake. Note that different flavors of Controlled English make different choices. In the AECMA standard test is noun; at Caterpillar it is a verb. This difference underscores the need for each organization to create definitions that work well in their particular environment. Example from Boeing Here is an example of before and after from Boeing s Simplified English. Between the before and after statements is the checker output that gives advice (known as a critique ) on how to revise the text so that it complies with the Simplified English standard. If the checker detects nothing wrong with the sentence, the checker output just says No errors found. Jim Hoard has included brief comments that identify the standard in square brackets. These comments are not, of course, part of the checker s critiques. BEFORE: Position truck shield under main gear truck and mark locations on truck where truck shield clamps will attach. CRITIQUES: Two instructions possible error. [Only one instruction is allowed in a sentence, unless the actions are performed simultaneously.] Unapproved prepositions: under. Use: below, in, less than. [The preposition under is proscribed in SE. Alternatives are offered in the critique. You can choose one of them or rewrite the sentence to avoid a preposition altogether.] Missing articles truck shield, main gear truck, truck. [The English articles are to be used wherever they are appropriate in normal discourse. Telegraphic style is proscribed.] AFTER: Put the truck shield below the truck. Make a mark where the truck shield clamps attach. Humorous ous Rewr write Many people have read the article Cat Bathing as a Martial Art, by Bud Herron, published in the Saturday Evening Post. When I was teaching the engineers at Tektronix about Simplified English, I obeyed the guidelines to rewrite this article. Unsurprisingly, this rewrite took me four hours, and I had to look up every word in the approved dictionary. This experience certainly increased my resolve to put an authoring tool in place before implementing a version of Controlled English! Please look on our Web site <infomanagementcenter.com> to see before and after versions of these critical instructions. Both pieces are copyrighted and used by permission. BEST PRACTICES JUNE

14 TOOLS AND TECHNOLOGY TOOLS AND TECHNOLOGY POET Content Management Suite Tina Hedlund, Comtech Services The CIDM would be interested to learn about any members or newsletter subscribers who are using POET. If you are using POET and have information to share, please contact Tina Hedlund comtech-serv.com> For more information about POET CMS, go to their Web site < Documentation departments are under increasing pressure to produce more in less time. Customers expect customization and don t understand why they can t get it. Out of desperation, many documentation departments are looking to single sourcing and reusing content first, and, eventually, to customizing their documentation. We recommend taking a very close look at your current process to determine the right tool for your department and its processes. What tool(s) are authors using to create content? What are their deliverables? Are you publishing to the Web? Are you printing manuals? What workflow applications are being used throughout the corporation, and will the tool s workflow software integrate into the content management system? How are your deliverables produced? POET Content Management Suite (CMS), which was released in May 1998, seeks to integrate into current documentation processes. Once you create a predefined publications specification, POET CMS automatically breaks XML or SGML documents into components based on their component tags and stores the components in a central repository. The repository is based on POET s wellknown, object-oriented database, where authors can access and reuse components. There is no theoretical limit to the number of components that can be stored in the repository; hard disk space is the only limiting factor. Many content management systems rely on databases created by other vendors, but by using their own object-oriented database, POET has been able to make refinements that solve issues directly related to content management. Author uthoring ing Content POET CMS reduces the learning curve for those authoring content by integrating the POET CMS repository into familiar authoring applications. Plug ins for Abortext Adept and Epic, SoftQuad Xmetal, and Adobe FrameMaker+SGML create an integrated interface between the authoring application and the POET CMS repository. Authors check out, reuse, modify and update, and check in components from a familiar interface. After the author checks the component back into the repository, POET CMS automatically creates a new version of the component (preserving previous versions) and indexes it to allow searching. POET CMS includes a robust searching facility using Verity that allows authors to search by full text or metadata or to search for text within specified component tags. Metadata helps authors assign to components additional information that can be used to customize output targeted for specific audiences (novice, intermediate or expert) or specific releases. Because the repository is XML/SGML based, authors can process the content into multiple outputs using the XML/SGML publishing tools already in place. Because POET CMS integrates into the scripting and workflow software, much of the output can be generated automatically to reduce costs. When used with third-party XML/SGML publishing tools that use style sheets, it is possible to deliver content dynamically to the Web without tedious HTML conversion. At the completion of a project, POET CMS offers an Editions feature that takes a snapshot of the data for archiving purposes. No built-in facility currently exists for archiving components to free up disk space, but POET plans to build more archiving functionality into the product. It is currently possible to archive by making backups and automate the process using scripting. Off-site Collabora aboration Documentation departments often have staff off site who need access to the documentation. POET CMS offers plug ins for Cold Fusion combined with security features that allow authenticated users off-site access to the repository from any Web browser. Users can check out, modify, and check in components from anywhere in the world. Theoretically, dozens of people can work in the repository 54 JUNE 2000 BEST PRACTICES

15 TOOLS AND TECHNOLOGY at the same time without affecting performance. Performance can be affected in the unlikely event of more than twenty people attempting to check components in or out simultaneously. However, since at any one time most authors working in the repository will be writing content rather than checking components in or out, this performance limitation should have little impact. Authors can create variants of the referenced information to facilitate translation on the fly. Variants of the original component are linked to the original component. As authors create components, they can automatically let the translators know that the new component is ready. When the original component changes, workflow software can trigger an to translators, notifying them that there is text in the repository to be translated. In this way, the translators can get started immediately rather than waiting for the entire completed document. Translation memory applications integrate into POET CMS, allowing a completely automated process when POET CMS is used with workflow software. You can also use the Variants feature to customize documentation. Once you have produced a standard or baseline set of documentation, you can create variants to customize the documentation, while reusing much of the existing content. In this way, you can produce one off documents for important customers or target documentation to different skill levels while still getting the cost, quality, and labor efficiencies found with single sourcing. Process Management To manage the documentation process, POET CMS integrates into workflow applications. POET CMS integrates into Staffware 2000, but can be customized to work with any piece of workflow software. Documentation managers can track project progress through the workflow software and refine their processes through trial and error. The workflow applications permit you to automate much of the process: for example, as steps in the process are completed, the software sends triggers to notify authors, editors, translators, and managers that the next step in the process can begin. POET CMS Application Minolta GmbH in Hanover, Germany, is integrating POET CMS into their documentation processes. Minolta knew that they needed to quickly find a tool to fit their documentation process. While documenting photocopier, fax machine, and printer documentation that is translated into several languages, Minolta s documentation department was creating 50,000 75,000 pages of documentation to maintain every year. They needed a more efficient way to create their documentation because much of the information is redundant and reusable. They first decided to standardize on SGML because it is vendor neutral, not likely to become obsolete, and accessible from many applications. They then began looking for a tool that would support all their processes using SGML and found POET CMS. With POET CMS, they were able to create the granularity they needed to reuse information, use the Variants feature to support translation, and access and store previous versions using the Editions feature to comply with administrative and legal requirements. Minolta, as well as many other organizations, discovered that finding a tool that integrated with their process without having to tailor their process to a tool produced the results they were looking for: the ability to reuse information and create custom documentation while reducing production time. System Requir uirement ements POET recommends that the content server and the content client have the following hardware and software specifications: Content Server Windows NT 4.0 Solaris 2.6 HP-UX MB of RAM Pentium system (Windows NT) 100 MB free disk space to start (depending upon database size); no custom disk partitions needed Content Client Windows NT 4.0 Windows 95 Windows 98 Windows MB of RAM Pentium system 40 MB of free disk space BEST PRACTICES JUNE