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.

High-level process

Our FrameMaker conversion to DITA process included the following high-level steps:

  1. Evaluate and select an XML editor. We looked at MadCap Flare, AuthorIT, XMetaL, and oXygen. After much debate, we selected XMetaL.
  2. 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.
  3. 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.
  4. 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).
  5. 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.
  6. 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.
  7. 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!

About peahleah

Youngest of four, left home at 17, traveled the country, and wound up in Austin.

Posted on September 28, 2014, in Teaching, Workplace and tagged , , . Bookmark the permalink. 4 Comments.

  1. Michelle Mailey Noben

    Very informative post!

    I’m interested in more of your thoughts about the changing of job titles, especially since this aspect of your job position is important enough for you to take a proactive stance. How do you feel job titles reflect on your work or even you, on a personal level? As sort of an outsider to the technical communication field, I’m curious what the most desirable job titles might be. What are the descriptions used, and why one might be more prestigious or “respectable” than another?

    Michelle

  2. Hi Michelle—

    We produce a variety of materials for different teams, and our team no longer wants to be classified as technical publications or information development; “content” is more appropriate because we create all kinds of content: marketing briefs, recruitment brochures, community posts, online product information, and so on. I also think that “content” sounds fresh, innovative, and cool.

    I just read your profile, and I think information architect may be a great fit for you!

    Click to access Am_I_an_IA.pdf

  3. I’ve only had to use Framemaker once so far and it was for a course here at UW Stout. Is Framemaker the standard in technical documentation today? I found the program incredibly frustrating to use. I’m more accustomed to working with a program like InDesign.

  4. No, I think the industry is moving away from FrameMaker as more companies are offering online and mobile documentation and just providing a PDF isn’t a great user experience.

    In my experience, a lot of companies use MadCap Flare as it provides authoring and publishing capabilities in one tool, and it’s relatively cheap (approximately $1K for a single license). My company uses an XML editor (not Flare) and then a separate publishing tool, but I’ve used Flare in the past and it’s a great tool.

    http://www.madcapsoftware.com/products/flare/

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.