surviving the transition to dita: trusted partners can ease the pain

Surviving the Transition to DITA:Trusted Partners Can Ease the Pain

Nicki L Davis, PhD San Francisco STCnickinmr@gmail.com 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.