Integrating Cost Effective Information in a Global Organization
In late 2005, representatives from all companies in ITT Fluid Technology gathered to discuss global reuse of technical information. The following year, Technical Writers and Information Architects at ITT Fluid Technology built an Information Model together with Product and Safety Subject Matter Experts and people from the companies’ Marketing Departments. Our new information system, based upon DITA, Minimalism, and Information Mapping® (IMAP), was named Global Enterprise Content Management (GECM).
This system is now used in the migration of Installation, Operation, and Maintenance (IOM) manuals for pumps and mixers for water and other fluids. We expect GECM to grow; ITT has a great variety of market segments and types of information that could benefit from using our system. Other ITT products and other document types are planned for migration into GECM, and at this stage we have started working on necessary research and pilots for some of them.
The GECM integration happens in the local ITT companies or Value Centres. My fellow colleagues and I at the corporate GECM Shared Services team work to support the integration with
- Migration management
- Internal and external information
- Planning for integration of new products and deliverables
- Maintenance of the Information Model, the Style Guide, and other steering documents
- Training related to the documentation processes and tools
- Discussion forum to share experiences and suggest improvements
- Spot checks of content structures, folder structures, tagging, and presentation
- Technical support to Writers and Localization Coordinators
- Quality tests on the outputs
- Follow up on reuse, production costs, and translation costs
I would like to share some of my experiences from the GECM integration in several companies throughout USA and Europe, focusing on the processes and interaction we implement in the analysis, structuring, and creation of the information. I hope to give you a bird’s eye view of different aspects of this integration and dive into the details to illustrate these aspects.
Baking the Information Model
GECM was originally very much a pioneer project and the first at ITT to mainstream the documentation processes and reuse information for several manufacturing companies. All details were agreed upon for the first time, and it was necessary to enable high reuse and to get accurate and cost-effective information in our repository.
The definition of the term information model seems to vary between practices; for us it covers all critical aspects of the documentation process from the initial analysis through publication. Cost effective information is much more than the content and the technical solutions. It is also a question of knowing exactly what to do and how to do it at any given moment in the documentation process.
Before migrating to DITA and a new Content Management System, we needed this clearly stated:
- agreement on a common product categorization to enable a common folder structure in the Content Management System and in the distribution
- a consistent and complete documentation process with clearly defined roles and responsibilities for the different stages
- a common content structure for the output per product type that was in compliance with international standards and reader goals
- common guidelines for how to present different kinds of information in a clear and unambiguous way
- a common style guide and terminology that worked across the companies
The corporate Architecture Team working out these goals consisted of people from the different companies’ Marketing Departments, Technical Writers and Information Architects, and Product and Safety Subject Matter Experts. The team wanted to avoid getting us stuck in a growing pile of personal ideas about the processes, structures, and presentation of content. Therefore, the agreement was to select standard processes and guidelines that are proven to live up to certain requirements; any change of these processes and guidelines had to be proven to be better. The standards we use complement each other well:
- DITA in itself provides restricted use of elements and shares the principle of topic-based writing with IMAP.
- IMAP is a minimalist method for the entire process of information analysis, structuring, and presentation. It also contains guidelines for how to create titles, text, graphics, tables and lists to meet different reader purposes, and some standard phrases to foster recognition and reduce translation costs.
- Both IMAP and Minimalism use scientific research basically focusing on cognitive psychology; we changed from a design focus to a user focus.
Minimalism adds value to the user analysis and provides analytic methods to reduce unnecessary or redundant information in the authoring process.
- International standards such as the ANSI and ISO standards and the Machine Industry Directives have to be followed. They are basically logical and have so far shown to work according to the methods we have selected.
I would recommend to develop an Information Model of this kind first and take it into practice before purchasing expensive technical tools. The requirement lists of the tools you are about to purchase should be based upon the reality of your new organization and processes rather than a draft. Developing an Information Model and letting it mature in the organization is time consuming. Also, once expensive investments in tools are made, you gain on showing a pay-back and getting the production going as quickly as possible. Information that has been created according to the Information Model is proportionately simple and cheap to convert from other formats to DITA, so you should be able to show great results in a short time.
The Information Model Documents and Training Package
The users of the GECM Information Model are basically the Technical Writers and Information Architects. We have a set of steering documents and training packages for them to understand and follow the GECM Information Model correctly and consistently.
1. One reference document describes the technical aspects of the documentation:
- The DITA topic types
- Which elements are preferred for which purposes
- Required and optional metadata and attributes
- Document naming conventions
- Chapter naming conventions
- Cabinets and folder structure in the content repository
2. One document supports the documentation process. It contains descriptions of roles and responsibilities, job descriptions, and guidelines for analysis, structuring, authoring, and reviews. Also, this document contains examples and standard phrases and guidelines for how to handle typical challenges connected to rewriting legacy information, such as:
- How to chunk, group, and title information in a relevant way
- How to restructure tables or procedures with too much content
- How to avoid redundancy
The internal style guide works as a complement to the Chicago Manual of Style; it states how to write when the Chicago Manual of Style allows too many options or when it conflicts with reuse and filtering, translation, or other requirements.
Some adjustments have been made in these documents over time, but mainly these changes have consisted of adding clarifications and examples rather than changes to the instructions.
We are now at the stage where the GECM information system can be used by any ITT company for different purposes. It is important that they can benefit from the major part of the Information Model by adapting as much as possible of it, and only change where necessary for them to fit in. When new products or services start using our system, they need to develop their own product categorization and terminology, and each new output requires new analysis of the audience and content structure. Also, Marketing or Legal materials may require different style guides than the Technical Product Documentation.
Limit the Scope of Your Pilot
The pilot is a test environment and a basis for evaluation. In our own first pilot, we tested the documentation and translation processes, guidelines, and the technical environments simultaneously. We made it on time, but the experience was quite overwhelming. Being wise after the event, I would suggest breaking a very ambitious pilot into smaller and more manageable pilots. I can envision our forthcoming pilots to be delimited by their purposes:
One pilot should be performed in each local organization when a new product type and document type is introduced to the system, testing things like
- The documentation process in the organization, from the analysis stage to the authoring stage
- The steering documents
- The content structure and estimated content reuse
Another pilot is needed when the technical environment is implemented or changed, testing things like
- The editorial software
- The workflow in the Content Management System
- The translation workflow
- Bridges between the different tools
- Metrics for content reuse
- Styling of the outputs
I would also suggest the following to anyone wanting to avoid getting unpleasant surprises during the pilot:
- If this is the first time the writers and any other actors will work in the new documentation process, schedule extra time for multiple mistakes, feedback, training, and corrections.
- Limit the number of products or services you want to include in the output, depending on how complex the output is expected to be.
- NEVER use the pilot for publication!
- Stick to the original plan and do not expand the scope of the pilot while it is running.
We had some good results from our first pilot, and it is getting better. Using GECM, we managed to get 50 percent reuse when creating manuals for four pumps from four different product series and different companies in the USA and Europe. In the present migration of Installation, Operation, and Maintenance (IOM) manuals for pumps and mixers, we get a reuse of 75-95 percent, depending on the product design. The most striking benefit we have seen already is the reduced translation costs; they are related to the reuse and our strict guidelines, standard phrases, and terminology database.
Also, the information has improved in usability since it has been restructured and rewritten according to our authoring guidelines. Tests with typical end users of these manuals showed that the information is complete and easy to navigate and comprehend. These quotes reflect the test readers’ overall impression of the new manuals:
- “This IOM is better than it has been for ages!”
- “Very complete IOM.”
- “Don said that our IOM is the best he has seen in his experience, even better than his own car manual!”
We did not count on it, but even errors showed to be easier to detect in the topic reviews. In some cases, information had been wrong in the legacy materials for ages without anyone noticing until it was restructured and clearly written according to our new guidelines.
Implementation of the User Perspective
The user perspective is one of our success factors. Focusing on the user perspective, we cannot only provide the information that is necessary for the reader to accomplish his or her job, but we can also exclude information that many times hinders the reading.
In the pre-study, we did some research about the end users that we thought would make sense to the content. We could then create about ten personas, representing different types of end users, and describe issues that were relevant to the content and the output:
- How they use the manuals
- How familiar they are with the subject
- What other technical information they use in their work
- How they normally find technical data, drawings, and so on
- How their working environments look
- Which media they feel comfortable using to get their information
We found that most users of the pump manuals are experienced engineers of late middle age. Even though their roles vary, they are familiar with technical terminology and drawings. They also have a traditional view of user manuals and expect them to be printed on paper. These results give us a pretty clear view of how to present and distribute the user manuals today. It also alerts us to prepare for a generation shift in the not too distant future. The personas are useful for the Information Architects when planning the content. While authoring, the writer can use the personas to define if there is any need of definitions, illustrations, or examples for the users to grasp the information or a summary to quickly move forward.
The plan for the content and the content structure is many times called the information model, but we do not want to create confusion by using this term in this context. We use task analysis to plan for new content for an entire manual for a product type or a new chapter or section for a product series. The Information Architect runs the task analysis together with Subject Matter Experts and Technical Writers. This way everyone achieves the same understanding of which information is needed for the readers to perform their tasks related to the manuals. The task analysis procedure is quite straight forward:
1. Define the users of this information; select and adjust the personas to get the right picture of them.
2. List all the tasks the readers have to accomplish related to each chapter in this manual.
3. List what the reader needs to know to perform each task: how the product looks, necessary tools, data, potential risks, and so on.
4. Define which tasks the readers already know how to accomplish. These will not become task topics in the output.
5. Define which of this necessary information the reader already knows or normally finds elsewhere. This information is not needed in the output.
It is important to keep and use the documentation from the task analysis, keeping track of why certain information makes sense at a certain place in the output. Installing, operating, and servicing mechanical equipment is mainly linear; there are few optional ways of doing the work. Therefore, the documentation from a task analysis is simply a table with one column for the tasks and one column for the information needed to accomplish the tasks. When planning the structure for software or similar content, where several procedures branch, the relationship between information is probably easier to visualize in flowcharts.
Communication Between Writers and Subject Matter Experts
The combination of a writer and a Subject Matter Expert (SME) is unbeatable when creating information for a third party. We have a great variety of products and manufacturers at several sites, and Technicians and Safety and Standards Experts are the SMEs on site. To create useful and accurate user manuals, the communication between the technical writers and these SMEs is necessary.
The SMEs provide the writer the necessary data and procedures for using the products. The SMEs also check that the information is accurate and complete and make sure that hazard statements protect the user from potential risks according to the product risk analysis.
The writers are the experts in how to communicate to the readers. They work in the Content Management System and Editorial Tool. They use their analytical and linguistic competence to ensure that the reader’s requirements are met in text and graphics, to write consistently and minimally, and to make the content searchable by creating effective titles and short descriptions.
In each project there is also a communication link between the SME and the Information Architect: at the Task Analysis meeting, the Information Architect makes sure that the SMEs understand and agree with the scope of the project, the user analysis, and the content analysis. At this meeting, they also agree on when and how the SMEs will provide their knowledge and missing materials to the writer.
We added a role, the Value Centre Contact, to support the communication between the Information Architect or Technical Writer and the SMEs. This role is important when the Information Architect and the writers are not in-house, as many questions are easier to solve face to face and informally than through e-mails, telephone, and WebEx meetings.
Integration Takes Time and Training
New processes, tools, and guidelines to accomplish structured writing takes a lot of time and training to integrate. How long it takes depends on the individual’s attitude more than anything, but also the attitudes in their environment. Therefore, it is critical for each organization, company, or department that wants to use the new documentation system to understand and approve its information model and prepare their organization to fulfil its part of the job. The time and training the individuals need also depends on their previous experiences. Technical Writers without previous experience of structured writing might need to practice and get training and feedback through several projects before they are entirely comfortable in the new way of working.
One of our local Information Architects in one of our European companies recently referred to her third task analysis meeting, where the participants had decided to lift certain information out of the user manual, as it was marketing information and did not support the end users of the manuals to accomplish their job. This illustrated how the local Information Architect had adopted the user perspective when planning for the information content and made the technical Subject Matter Experts for the product series do so too. She told me with a great smile on her face: “They understand the Technical Information in a completely new way since we started running the task analysis meetings!” This moment of insight is one important kind of milestone in the integration of the GECM information model in our organization!
About the Author
ITT Fluid Technologies
Kristina is an Information Architect in the ITT corporate Global Enterprise Content Management (GECM) Shared Services. She trains local information developers, tests and maintains the corporate information model, and sets up implementation processes for new information areas. Kristina has a University Diploma in Swedish Language Consultancy, graduating from Stockholm University. She has been working as a plain language expert and certified Information Mapping instructor since 1996.
Kristina has co-authored a paper for the PTC User World Event 2008 on the GECM system and presented a paper at the DITA Europe Conference 2008 on strategies for comprehensible and reusable content.