Many companies are moving their content to DITA, a process that can be daunting for players who are new to such migrations and might not fully understand what they are getting into. In this practical, from-the-trenches presentation, you’ll learn from the experience of a team of 8 writers tasked with converting 10,000 pages of unstructured legacy content into structured (“intelligent”) DITA content. We describe problems encountered and provide suggestions for making things go more smoothly. A critical factor in the success of the project was the use of expert partners for some tasks. The net result was clearer, more usable content and greater expertise for the writing team at a substantial savings over doing it all ourselves.

1. Nicki L Davis, PhD San Francisco STC
nickinmr@gmail.com 19 August 2015

2. • Introduction
• Project initiation
• Content analysis
• Writer training and pilot
• Content conversion
• Lessons learned
• Q&A

6. “Nobody should have to go through this to get their work done!”

7. “Nobody should have to go through this to get their work done!”

8. Darwin Information Typing Architecture
XML
Topic-based authoring
3 information types: task, concept, and
reference
Semantic markup: based on meaning, not
formatting

9. Non-semantic (unintelligent) Semantic (intelligent)
1. Click the Alert button.
The Create/Edit Alert dialog
box appears.
2. On the Create/Edit Alert
dialog box, select the Enable
check box.
The Enable check box is
located at the bottom of the
dialog box.
1. Click the Alert button.
The Create/Edit Alert dialog
box appears.
2. On the Create/Edit Alert dialog
box, select the Enable check
box.
The Enable check box is
located at the bottom of the
dialog box.

10. PDF Smartphone
1. Click the Alert button.
The Create/Edit Alert dialog box
appears.
2. On the Create/Edit Alert dialog
box, select the Enable check box.
The Enable check box is located
at the bottom of the dialog box.
Click the Alert button.
On the Create/Edit Alert dialog box,
select the Enable check box.
The Enable check box is located at
the bottom of the dialog box.

12. *Mandatory element
These elements come from the Darwin Information Typing Architecture (DITA)
standard, but are not restricted to DITA.
Topic element User question
Context What is a frammis and why would I want to kreeble it?
Prerequisite Do I need to do anything before I kreeble the frammis?
*Steps How do I kreeble the frammis?
Result How do I know I’ve completed the procedure
successfully and the frammis really is kreebled?
Example Can you show me an example that uses this procedure?
Postrequisite Do I need to do anything after I kreeble the frammis?

14. Device proliferation
Content silos
• Duplication of effort
• Content lacked standardization and
consistency
• Individual stakeholders had only a limited
grasp of the big picture

15. • Evaluate tools: Component content
management system (CCMS) and authoring
tools
• Choose vendors for tools and other services
• Determine where we needed outside help
• Calculate costs
• Negotiate with vendors
• Submit proposal and get management
approval
• Manage training and rollout to writing team

16. Partnership Report Card
Partner Activity Mark
Analyze content
Train writers in DITA
Train writers in XML and CMS tools
Assist with information model (pilot)
Assist implementation of CCMS (pilot)
Create publication scripts
Create conversion scripts
Clean up migrated content

18. Problem Design Goals
People want Google, we delivered books • Put all user documentation in one place
• Provide navigational context
• Provide versioning
Internal users created overlapping content;
volume not maintainable
• Technical documentation deliverables
must be fully searchable with Technical
Support external website.
• Establish clarity of ownership
(governance)
SMEs frustrated by overlapping content
and glacial pace of review/correction cycle
• Allow SMEs to comment on topics, and
have that feedback delivered directly to
the writer in charge
No information on which pages (out of
10,000 - 20,000) are viewed most often
• Provide analytics to prioritize work on
content

19. Partnership Report Card
Partner Activity Mark
1 Analyze content A
Train writers in DITA
Train writers in XML and CCMS tools
Assist with information model (pilot)
Assist implementation of CCMS (pilot)
Create publication scripts
Create conversion scripts
Clean up migrated content

21. Our existing CCMS did not meet our
requirements.
Core team found two CCMS vendors whose
systems did meet our requirements.
Both systems required Darwin Information
Typing Architecture (DITA).
Writing team evaluated each system for one
week in mid-2010.

22. 1-week training class in DITA
3-day training class on the CCMS
6-month pilot to develop information model
and implement CCMS
Books on DITA

23. One partner (#2) helped train writers in DITA and
helped with the information model
CCMS vendor (#3) helped train writers on the CCMS
and implement selected CCMS features
Individual writers conducted research projects in
areas of interest (context-sensitive help, reuse
strategy, cross-references, and so on.)
Writers devoted about 20% of their time to the pilot
Writing team met weekly in conference call with
partners

24. Partnership Report Card
Partner Activity Mark
1 Analyze content A
2 Train writers in DITA A
3 Train writers in XML and CCMS tools A
2 Assist with information model (pilot) A
3 Assist implementation of CCMS (pilot) A
Create publication scripts
Create conversion scripts
Clean up migrated content

26. Old CCMS
Export
Import to new CCMS
DITA
Convert
XML
Staging
Server
Production
Server
Output
Publish
Transfer
Clean up

27. Non-semantic (unintelligent) Semantic (intelligent)
1. Click the Alert button.
The Create/Edit Alert
dialog box appears.
2. On the Create/Edit Alert
dialog box, select the
Enable check box.
The Enable check box is
located at the bottom of the
dialog box.
1. Click the Alert button.
The Create/Edit Alert dialog
box appears.
2. On the Create/Edit Alert
dialog box, select the Enable
check box.
The Enable check box is
located at the bottom of the
dialog box.
<p> to ??
<p> to ??

28. Non-semantic (unintelligent) Semantic (intelligent)
1. Click the Alert button.
The Create/Edit Alert dialog
box appears.
2. On the Create/Edit Alert
dialog box, select the Enable
check box.
The Enable check box is
located at the bottom of the
dialog box.
1. Click the Alert button.
The Create/Edit Alert dialog
box appears.
2. On the Create/Edit Alert dialog
box, select the Enable check
box.
The Enable check box is
located at the bottom of the
dialog box.

29. Original As migrated
1. Click the Alert button.
The Create/Edit Alert dialog box
appears.
2. On the Create/Edit Alert dialog
box, select the Enable check box.
The Enable check box is located
at the bottom of the dialog box.
1. Click the Alert button. The
Create/Edit Alert dialog box
appears.
2. The Create/Edit Alert dialog box
appears.
3. On the Create/Edit Alert dialog
box, select the Enable check box.
The Enable check box is located
at the bottom of the dialog box.
4. The Enable check box is located
at the bottom of the dialog box.

30. Original content Variations in output
Note: Lorem ipsum dolor sit amet,
consectetur adipiscing elit. Duis ac
consectetur mauris. Cras in diam nisl.
Note:
Lorem ipsum dolor sit amet, consectetur
adipiscing elit. Duis ac consectetur
mauris. Cras in diam nisl.
Note:
Lorem ipsum dolor sit amet, consectetur
adipiscing elit. Duis ac consectetur
mauris. Cras in diam nisl.

31. Partnership Report Card
Partner Activity Mark
1 Analyze content A
2 Train writers in DITA A
3 Train writers in XML and CCMS tools A
2 Assist with information model (pilot) A
3 Assist implementation of CCMS (pilot) A
2 Create publication scripts D
2 Create conversion scripts F
4 Clean up migrated content A

33. You won’t really understand intelligent
content and semantic markup until you’ve
done it on your own content.
Professional DITA training and assistance with
information model during pilot worked well.
CCMS vendor support during pilot kept things
running smoothly.
Mechanics of moving from unintelligent to
intelligent content are challenging.
Manual cleanup is no fun.
Intelligent content rocks!

34. When a partnership works, it saves time and
prevents frustration.
Go for a partner with experience in the areas
where you need help.
Be careful about setting expectations!
Don’t underestimate the complications of
conversion and publication scripts
Even with the inexperienced partner, it was
still worth it to get outside help.

35. • Beth Fryer, Timothy Martin, Dan Claessens
• Faith Weber, Doug O’Neill

37. • “Smoothing the Transition to DITA: Expert
Partners Can Ease the Pain”. STC Summit
2015 Proceedings, pp. 67-70
• Webinar:
http://www.dclab.com/webinars/case-
study-the-value-of-partnership-during-
conversion.