Migration to DITA:
A Retrospective
Ed Hartman,, Jon Kieffer,, Evan Olson
Fujitsu Network Communications Inc.
INTERNAL USE ONLY
Agenda
 About Fujitsu
 Our documentation
 Reasons for going to DITA
 History of our migration experience
 Tools
 Key decisions
 Custom development
 Open issues and challenges
INTERNAL USE ONLY
About Fujitsu Network Communications Inc.
Subsidiary of Fujitsu Limited
Multiservice
Provisioning Platform
ROADM/DWDM
Network Design
& Management
Packet Optical
Networking
g
INTERNAL USE ONLY
Multiservice
P
Provisioning
i i i
Platform
Pl tf
Documentation Pre-DITA
 Department of 30 with 20 writers
 Large documentation sets
(8,000+ pages, typical)
 Many cross-reference links
 Tools: Structured Framemaker
 Output: pdf, web help
 Doc sets reissued many times over
long market life (15 years or more)
INTERNAL USE ONLY
Documentation Life
Product
INTERNAL USE ONLY
Documentation Reissue
Product
Release 1.1
Release 7.1
INTERNAL USE ONLY
Content Migration Required
Product
Transition to DITA
INTERNAL USE ONLY
Reasons for going to DITA
 Open standard, XML
 Topic-based authoring
 Improve efficiency and quality through reuse
 On-demand custom documents
INTERNAL USE ONLY
Changing Goals
 Initial (High hopes)
 Define
D fi a model
d l ffor b
best-practice
t
ti DITA,
DITA then
th migrate
i t allll
content to it
 Later
L t (Realistic)
(R li ti )
 Migrate current content to DITA without much change
 Author new documents according to best-practice DITA
INTERNAL USE ONLY
History of Experience
Phases
1 Experimentation
1.
E
i
t ti and
dL
Learning
i
2. Pilot Projects
3. Major Migration
Current Position
INTERNAL USE ONLY
History of Experience
Phase 1: Experimentation and Learning
 Books,
B k workshops,
k h
webinars,
bi
experimentation
i
t ti
 Developed a vision for best-practice DITA
Developed authoring models
Topic reuse with variation (using conrefs)
Scenario-based guided navigation
Feature-based authoring
Key Goal: Avoid coupling topics (cross-references)
INTERNAL USE ONLY
History of Experience
Phase 2: Pilot Projects
 NETSMART 2000
• Small, very successful
• Automation followed by heavy re-authoring
NETSMART 2000 Documentation Migration to DITA
1154.75
DITA Pilot Project
583
488
426.5
288
Total hours
for
NETSMART
2000 V3.1
INTERNAL USE ONLY
Total Hours
for
NETSMART
2000 V3.2
Total hours
for
NETSMART
2000 V3.3
Total hours
for
NETSMART
2000 V4
Total hours
for
NETSMART
2000 V4.1
12
History of Experience
Phase 2: Pilot Projects
 FLASHWAVE 4500
• Large, abandoned
re authoring is unrealistic
• Discovered that heavy re-authoring
• Discovered that elimination of cross-references is unrealistic
INTERNAL USE ONLY
History of Experience
Phase 3: Major Migration
 Product-by-product
P d tb
d t
 Pregrooming  Automation  Postgrooming
 Training
T i i and
d llearning
i (i
(in parallel)
ll l)
 Cross-references:
Migrated cross-references
cross references to xrefs
(Technically challenging, but accomplished)
INTERNAL USE ONLY
Automated Conversion Process
INTERNAL USE ONLY
Current Position
 Documentation now in DITA
 Structure mirrors pre-DITA (warts and all)
INTERNAL USE ONLY
Tools
 CMS
Aquired Vasont before we even thought about DITA
Started using with large XML files that took forever to extract and load
Realized modular content was essential to make CMS work for us
 Authoring Tools
FM + XML  FM + DITA  <oXygen/> Author + DITA
(
(with
brieff XMetal evaluation))
 Production Tools
1 FM  PDF; WebWorks  Help
1.
2. <oXygen/>/DITA-OT/AH  PDF
<oXygen/>/DITA-OT  WebHelp
INTERNAL USE ONLY
Key Decisions
Topics
Standard
St d d topics
t i (no
( specialization)
i li ti )
Concept topic versus reference topic
C
Conref
f targets
t
t stored
t d together
t
th in
i separate
t files
fil
Elements
Small set; avoided extensive use of domain elements
Topic Filenames
Adopted the un-strategy file-naming convention
INTERNAL USE ONLY
Un-Strategy Filenaming
March 2008 meeting of Silicon Valley DITA Interest Group (SVDIG)
http://blogs.oracle.com/coolstuff/entry/svdig notes airhelp naming
http://blogs.oracle.com/coolstuff/entry/svdig_notes_airhelp_naming
INTERNAL USE ONLY
Un-Strategy Filenaming
Topic title in ditamap
C ti fil
Cryptic
filenames
INTERNAL USE ONLY
Custom Development
 Extensive customization of DITA-OT for PDF
 Solved the problem of external cross references
 Re-designed layout (headers, footers, fonts, graphics)
 Added Antenna House extensions for document
properties, float text, colored bookmarks, & change bars
 Customized <oXygen/>
yg
WebHelp
pp
plug-in
g
 Created collections for maps, concepts, references and
tasks in Vasont
 Developed numerous XSLT transform scenarios for use in
<oXygen/> Author.
 Enhanced
E h
d CSS ffor authoring
th i iin <
<oXygen/>
X
/>
INTERNAL USE ONLY
Open Issues and Challenges
 Replace cross references with keyref, relationship
tables and conrefs
tables,
 Simplify authoring using DTD constraints and more
automation
 Improve content sharing and workflow
 Get everyone on the same page with respect to
goals
 Define good standards and manage compliance
INTERNAL USE ONLY
Questions?
INTERNAL USE ONLY