Sometimes, a spontaneous road trip can be a lot of fun, as long as you’re willing to take the good with the bad—getting lost, car trouble, unfriendly (or just plain weird) natives, bad diner food. Usually, though, the most successful trips involve planning, roadmaps, and best of all, guidance from people who’ve already been there. The journey from traditional, deliverable-centric content creation to DITA-based content creation falls into this second category. In this session, we talk about one small publication group’s experience moving to DITA, from the initial discussions to the successful implementation of a FrameMaker-based, end-to-end publication process. Here are some of the high points of the project; we’ll discuss our decision-making process and some of our technical approaches in detail in the session.

2. About the Trip to DITA
The transition from traditional, document-centered content creation to DITA-
based content creation requires substantial planning for the journey to be
successful.
The journey of one small documentation team took from unstructured Frame to
Structured FrameMaker using the DITA content model. This will include
initial discussions, strategic development and steps required for a successful
implementation of a FrameMaker-based, end-to-end publication process.

3. About this Presentation
 An overview of the migration from unstructured to structured authoring
 A specific process for preparing FrameMaker documents for conversion to
DITA.
 Challenges faced during the year-long journey from unstructured to
structured authoring.
 A model other documentation teams can use to re-organize existing
documents and to create new documents going forward to help ensure their
FrameMaker content is well-positioned for a successful, efficient
conversion effort.

4. Interviews and Report
 Interviews with team members and group
discussions
 Focus on business drivers, team readiness, content
analysis, tools and disparate processes.
 Offered an opportunity to discover team members’
preparedness.
 Report outlined summary of findings with
requirements and action plan for a phased
implementation.
 Recommendations, detailed development steps
and basis of agreement.

5. Goals
 Optimize authoring, translation and publishing
cycle to help meet increased need for translations
 Reuse content from one publication to another
quickly and consistently
 Decrease time to develop and update manuals
 Automate labor-intensive tasks giving writers
more time for research and improving content
 Prepare for a future Content Management System
(CMS) implementation

6. Budget
Client workgroup gathered information for a year
prior to contacting consultant. Spread expenses over
two years and four phases.
 Phase 1: Assessment of business goals,
requirements analysis, content audit, content
analysis, process mapping and process re-
engineering
 Phase 2: DITA training, content modeling,
prototype project, assess content management
technologies
 Phase 3: Write a CMS RFP based on business
requirements, distribute RFP to potentials vendors,
proof of concept with qualified vendor(s)
 Phase 4: Buy and implement CMS

7. Content Audit
 Writers selected three publications representative
of their work products
 Consultants worked with client team to performed
content audit
 Determine how well content could be broken
into topics
 Determine what rewrite required
 Develop method for determining reuse
 Spreadsheet for tracking
 Selected book with most reuse (the beta book,
80%) and used that for development

8. Content Modeling
 DITA was selected as the content model
 Content modeling focused on chunking topic by
types and identifying attributes audience, product,
language, software version and compliance
requirements
 Used content audit spreadsheet as a guide
 Content modeling was a client training exercise

9. Tool Selection
 Hard copy and PDF formats only
 Primary requirement is PDF for print
 Writers had no experience with structured
authoring
 Writers already experienced Frame users
 Migrated from unstructured (7.1) to structured
9
 Completely Frame based publishing process
preferable to an XSL-FO publishing process
 Using default DITA functionality, not DITA-FMx
 Yeah, we know FMx is better!

10. Reuse
 Based on content audit:
 Text: 85%
 Graphics: 70%
 Three products, four document types
 Import XML software file as conrefs for variables
 Conditions

11. Clean Template
 Standardize style names, eliminate un-used styles
 Clean and standardize all templates before
conversion
 Client made good decisions to simplify template
for translation:
 No hyphenation
 No text in cross-references

12. Conditions
 Eliminated conditional text and replaced with
@product, @audience (pick list built in EDD)
 Structure changes needed to accommodate
 Decisions made about level of granularity for
these attributes
 topic-level
 element-level
 sentence level?
 phrase level?
 More tracking required with last two levels

13. EDD
 Based on “default” DITA EDD that ships with
FrameMaker
 Unnecessary rules removed or simplified
 Client uses only ~40% of tagset but unused
elements not deleted from EDD
 Use of @outputclass on several elements to
specify formatting not predictable via context
 Full-page images vs in-column images
 Ad hoc table cell alignment
 No specialization or DITA plug-ins

14. Conversion Table
 Template standardization
 Template style usage very consistent—YAY!
 “Crosswalk” spreadsheet developed to map
existing template styles to equivalent DITA
elements

15. Document Conversion
 Conversion table “wrapped” every instance of a
format in the appropriate element
 Higher-level wrapping largely manual—writer
discretion needed to determine appropriate topic
type, etc.
 Converted each chapter document into one large
XML doc
 Consultants/writers then determined how to “split”
large doc into individual topics
 Naming convention
 Not a mass conversion
 Consistent level of granularity

16. Variables
 Original template contained 100+ variables
corresponding to menu options in software
 Value of variables came from developer-generated
XML file
 Easily translatable; kept this functionality
 Created separate file containing each variable as a
conref source (<varname>)
 This file still developer-generated, though now
in DITA
 Still easily translatable

17. Images
 Most images in original documents were line
drawings of screen overlaid with text boxes
containing variables, simulating screen shots
 Easily translatable, reduced need for language-
specific images
 Initial goals was to use SVGs (Scalable Vector
Graphics) to maintain this functionality (i.e.
translatable text as element within SVG)
 FrameMaker cannot “look inside” SVG code; this
solution not workable at present
 For same reason, cannot show/hide callouts
(Frame cannot interpret the @display value)
 Use SVGs to lay groundwork for CMS

18. Images
 Image sizing
 Frame uses DPI, converts to @height, @width
 No units in XML code
 @height, @width not accessible in Frame
 Image paths
 Frame uses backslashes by default
 Cannot enter backslashes manually, must
change to forward slashes
 Re-linking image via Missing File dialog does not
dynamically update @href path

19. Translation
 Prefix for <note> elements, some <title> elements
and other items language-specific
 Decision made to generate these items using EDD
rules based on @xml:lang
 One template per document type vs. separate
template for each language
 Non-English PDFs produced by the translation
agency, so this simplification was essential
 Numbering/bulleting not language-specific but
groundwork laid if changes in future

20. Tables
 Table handling
 Mapping between DITA table elements/
attributes handled by read/write rules
 Trick is learning what corresponds to what in
Table Designer and Custom Ruling & Shading
dialogs
 Most formatting applied based on <tgroup>
not <table>
 <colspec>, <spanspec> in XML code but not in
Frame—can be confusing

21. Revisit Template
 Client focused on page layout
 Ad hoc tables modifications required narrowing
 Impact on EDD
 Revisions along the way; discovery of
“exceptions”
 Writers rethinking items in light of increasing
DITA knowledge

22. Beta Project
 Representative of typical book but not a
production project
 Used to test every aspect of development from
topic types, templates, EDD, conversion, reuse,
book building and training.
 Smaller sample of beta book for translation testing
 Project book is leveraged for production

23. AXCM
 Free Frame plug-in from West Street Consulting
 www.weststreetconsulting.com
 Filters files for @product, @audience using XPath
filters
 Colors documents to emulate conditional text
 Filters topics on the fly
 More robust than Frame’s built-in Filter By
Attribute
 For this publishing process, preferable to applying
a ditaval file

24. Basic Publishing Process
 Ditamap for each book chapter
 Save ditamap as composite Frame file
 Set numbering, other doc properties
 Not using “Prompt for Ditaval” option
 Not using bookmap
 Add composite Frame files to Frame book
 Filter files for @product, @audience using
AXCM
 Generate/update TOC, Index
 Publish book as PDF

25. Installation
 Upgrade to FrameMaker 9
 Set up structured application
 Install AXCM

26. Demonstration
 Three days on-site to rollout template
 Goals:
 Instruct writers in DITA authoring
 Get writers familiar with tagset
 Get writers familiar with Frame’s DITA
implementation and interface
 Explain conversion process
 Additional day on-site to instruct writers in basics
of EDD creation and maintenance
 Writers not ready to take over EDD but they
understand what’s “under the hood”

27. Workflow Requirements
 CMS is just one part of a unified content strategy
 Specification detailing client use case
 Requirements focus
 Support for DITA, content reuse, user
interface, support encoding for languages,
translation streaming and branching capacities,
automated, multi-channel publishing
 Cost
 Criteria for migration
 Use to produce a Request for Proposal (RFP)
include information about existing
implementations, licensing, configuration, core
technologies, maintenance, support,
customization, training and cost

28. Request for Proposal
 RFP is offered to major CMS vendors and vendors
are given the opportunity to respond.
 Evaluate responses
 Based on requirements, select vendors who
respond to the RFP with a proof-of-concept

29. Proof of Concept
 Beta book used for Proof of Concept
 Vendors use client content to demonstrate how
their system meets client needs
 Compare Proof of Concept results with CMS
Requirements
 Evaluate vendor relationship, expertise

30. Contact Information
 Mollye Barrett
ClearPath, LLC
www.clearpath.cc
mollye@clearpath.cc
www.linkedin.com/in/mollyebarrett
 Leigh White
ElementalSource, LLC
http://elementalsource.pbworks.com/
elementalsource@gmail.com
www.linkedin.com/in/leighwwhite