surviving the transition to dita: trusted partners can ease the pain
TRANSCRIPT
Surviving the Transition to DITA:Trusted Partners Can Ease the Pain
Nicki L Davis, PhD San Francisco [email protected] 19 August 2015
Agenda
• Introduction• Project initiation• Content analysis• Writer training and pilot• Content conversion• Lessons learned• Q&A
Introduction
About Nicki Davis, PhD
About Nicki Davis, PhD
About Nicki Davis, PhD
“Nobody should have to go through this to get their work done!”
About Nicki Davis, PhD
“Nobody should have to go through this to get their work done!”
What is DITA?
Darwin Information Typing ArchitectureXMLTopic-based authoring3 information types: task, concept, and referenceSemantic markup: based on meaning, not formatting
Semantic markup makes your content intelligent
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.
Intelligent content adapts to different devices
PDF Smartphone1. 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.
For writers, semantic markup rocks!
Example: “How to kreeble a frammis”
*Mandatory element
These elements come from the Darwin Information Typing Architecture (DITA) standard, but are not restricted to DITA.
Topic element User questionContext 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?
Project Initiation
Content crisisDevice proliferationContent silos• Duplication of effort• Content lacked standardization and
consistency• Individual stakeholders had only a limited
grasp of the big picture
Core team did the heavy lifting• 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
Eight tasks, four different partnersPartnership Report Card
Partner Activity Mark
Analyze contentTrain writers in DITATrain writers in XML and CMS toolsAssist with information model (pilot)Assist implementation of CCMS (pilot)Create publication scriptsCreate conversion scriptsClean up migrated content
Content Analysis
Results of content analysisProblem Design GoalsPeople 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
Report card for content analysisPartnership Report Card
Partner Activity Mark
1 Analyze content ATrain writers in DITATrain writers in XML and CCMS toolsAssist with information model (pilot)Assist implementation of CCMS (pilot)Create publication scriptsCreate conversion scriptsClean up migrated content
CCMS Vendor Selection, Writer Training, and Pilot
Selecting a CCMS vendor
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.
Preparing the writing team for the change
1-week training class in DITA3-day training class on the CCMS6-month pilot to develop information model and implement CCMSBooks on DITA
PilotOne partner (#2) helped train writers in DITA and helped with the information modelCCMS vendor (#3) helped train writers on the CCMS and implement selected CCMS featuresIndividual 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 pilotWriting team met weekly in conference call with partners
Report card for writer training & pilotPartnership Report Card
Partner Activity Mark
1 Analyze content A2 Train writers in DITA A3 Train writers in XML and CCMS tools A2 Assist with information model (pilot) A3 Assist implementation of CCMS
(pilot)A
Create publication scriptsCreate conversion scriptsClean up migrated content
Content Conversion, Cleanup, and Publication
Process overview
Old CCMS
Export
Import to new CCMS
DITA
Convert
XML
StagingServer
ProductionServer
Output
Publish
Transfer
Clean up
Some cleanup is always necessaryNon-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 ??
Use default elements to map non-semantic to semantic markupNon-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.
Unexpected conversion issuesOriginal As migrated1. 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.
Unexpected publication issuesOriginal 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.
Report card for content conversion publication, and cleanup
Partnership Report CardPartner Activity Mark
1 Analyze content A2 Train writers in DITA A3 Train writers in XML and CCMS tools A2 Assist with information model (pilot) A3 Assist implementation of CCMS (pilot) A2 Create publication scripts D2 Create conversion scripts F4 Clean up migrated content A
Lessons Learned
For WritersYou 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!
ForManagersWhen 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 scriptsEven with the inexperienced partner, it was still worth it to get outside help.
Give credit to the core team
• Beth Fryer, Timothy Martin, Dan Claessens
• Faith Weber, Doug O’Neill
Q&A
References• “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.