surviving the transition to dita: trusted partners can ease the pain
TRANSCRIPT
![Page 1: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/1.jpg)
Surviving the Transition to DITA:Trusted Partners Can Ease the Pain
Nicki L Davis, PhD San Francisco [email protected] 19 August 2015
![Page 2: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/2.jpg)
Agenda
• Introduction• Project initiation• Content analysis• Writer training and pilot• Content conversion• Lessons learned• Q&A
![Page 3: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/3.jpg)
Introduction
![Page 4: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/4.jpg)
About Nicki Davis, PhD
![Page 5: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/5.jpg)
About Nicki Davis, PhD
![Page 6: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/6.jpg)
About Nicki Davis, PhD
“Nobody should have to go through this to get their work done!”
![Page 7: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/7.jpg)
About Nicki Davis, PhD
“Nobody should have to go through this to get their work done!”
![Page 8: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/8.jpg)
What is DITA?
Darwin Information Typing ArchitectureXMLTopic-based authoring3 information types: task, concept, and referenceSemantic markup: based on meaning, not formatting
![Page 9: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/9.jpg)
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.
![Page 10: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/10.jpg)
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.
![Page 11: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/11.jpg)
For writers, semantic markup rocks!
![Page 12: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/12.jpg)
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?
![Page 13: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/13.jpg)
Project Initiation
![Page 14: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/14.jpg)
Content crisisDevice proliferationContent silos• Duplication of effort• Content lacked standardization and
consistency• Individual stakeholders had only a limited
grasp of the big picture
![Page 15: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/15.jpg)
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
![Page 16: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/16.jpg)
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
![Page 17: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/17.jpg)
Content Analysis
![Page 18: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/18.jpg)
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
![Page 19: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/19.jpg)
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
![Page 20: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/20.jpg)
CCMS Vendor Selection, Writer Training, and Pilot
![Page 21: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/21.jpg)
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.
![Page 22: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/22.jpg)
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
![Page 23: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/23.jpg)
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
![Page 24: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/24.jpg)
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
![Page 25: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/25.jpg)
Content Conversion, Cleanup, and Publication
![Page 26: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/26.jpg)
Process overview
Old CCMS
Export
Import to new CCMS
DITA
Convert
XML
StagingServer
ProductionServer
Output
Publish
Transfer
Clean up
![Page 27: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/27.jpg)
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 ??
![Page 28: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/28.jpg)
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.
![Page 29: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/29.jpg)
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.
![Page 30: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/30.jpg)
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.
![Page 31: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/31.jpg)
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
![Page 32: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/32.jpg)
Lessons Learned
![Page 33: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/33.jpg)
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!
![Page 34: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/34.jpg)
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.
![Page 35: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/35.jpg)
Give credit to the core team
• Beth Fryer, Timothy Martin, Dan Claessens
• Faith Weber, Doug O’Neill
![Page 36: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/36.jpg)
Q&A
![Page 37: Surviving the Transition to DITA: Trusted Partners can Ease the Pain](https://reader036.vdocument.in/reader036/viewer/2022081520/58eb9fa01a28abd14c8b469d/html5/thumbnails/37.jpg)
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.