FrameMaker conversion to DITA
Digital Literacy for Technical Communication was written specifically for me! Many items described in the first two chapters—recent introduction of Darwin Information Typing Architecture (DITA), structured authoring and reuse, implementation of a content management system (CMS), transition of job and team titles, and participating in agile development methodology—affect me directly.
Job title and team name transitions
Digital technology has personally changed my job, job titles, and team name in less than two years at Hewlett-Packard. In July 2013, I started as a contract technical writer on the Technical Publications (Tech Pubs) team.
Four months later, I was converted to a full-time employee and my job title was replaced: information developer. Around this same time, my manager decided that our team would be called Information Development (Info Dev).
Last May, our division was restructured and our team name changed for a third time; we are now called Content Development and Delivery (Content). Moreover, since I managed the FrameMaker conversion to DITA project, I plan to renegotiate my job title at my annual performance review next month to information architect.
We also work on small teams (based on our product offerings) that incorporate the agile development methodology.
FrameMaker conversion to DITA
This past year, I championed a project—including tracking and documenting the entire process—that converted our FrameMaker product library into DITA.
What is DITA?
In Saul Carliner’s chapter “Computers and Technical Communication in the 21st Century”, he describes DITA as an XML-based architecture that divides content into small, self-contained chunks of information that can be reused into several different communication products (pg. 42).
The highest structure in DITA is a topic: a single XML file. DITA has three main topic types: concept, task, and reference. In her book, Introduction to DITA Second Edition: A Basic User Guide to the Darwin Information Typing Architecture, Including DITA 1.2, JoAnn Hackos defines the three topic types with questions:
- Concept: What is this about?
- Task: How do I?
- Reference: What else? This information may also include APIs, error messages, or command line reference lists.
All of the DITA topics can then be assembled, prioritized, and collected into a DITA map—basically a Table of Contents.
Our FrameMaker conversion to DITA process included the following high-level steps:
- Evaluate and select an XML editor. We looked at MadCap Flare, AuthorIT, XMetaL, and oXygen. After much debate, we selected XMetaL.
- Conduct a content inventory to identify and prioritize which FrameMaker books to convert. In addition to documenting software, we also document hardware, and decided to keep these guides in FrameMaker—it’s static content that does not change very often. We also decided to keep our legacy software releases in FrameMaker and only converted the latest version.
- Clean up the source FrameMaker files as much as possible before the conversion to ensure that just the right amount of information was included within a given Heading. Not all of our existing content was consistently structured to contain one concept, one procedure, or one set of reference information. We determined that the PDF generated from FrameMaker would be our source of record to verify that all content was correctly converted.
- Create and run a Mif2Go script to convert every FrameMaker Heading into its own DITA topic. The script also attempted to accurately transfer every paragraph and character tag in FrameMaker into the respective DITA <element> tag. Our library of approximately 1,000 pages (in PDF) converted into more than 4,000 DITA files (topics).
- Using the PDF generated from the FrameMaker source file, open the DITA map (and then each DITA topic) to verify that all content was properly formatted. This step took a significant amount of time to do as all 4,000 files needed additional clean up and validation.
- Use WebWorks to generate output for a DITA map. We created custom stationery files (specialized CSS) that transfers every DITA <element> into a specific look and feel (i.e., paragraph and character style). We have two types of output: PDF and HTML.
- Implement a content management system (CMS) to store all of our DITA files. We selected SDL, and our team training on how to use it starts tomorrow!