case study: the value of partnership during dita conversion
TRANSCRIPT
Nicki L Davis, PhD [email protected] STC Berkeley 9 July 2014
“Nobody should have to go through this to get their work done!”
“Nobody should have to go through this to get their work done!”
• Project initiation • Content analysis • Writer training and pilot • Content conversion • Lessons learned • Q&A
Device proliferation Content silos • Duplication of effort • Content lacked standardization and
consistency • Individual stakeholders had only a limited
grasp of the big picture
• Beth Fryer, Timothy Martin, Dan Claessens
• Faith Weber, Doug O’Neill
• Evaluate tools (CMS 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
Partner 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 CMS (pilot)
Create publication scripts
Create conversion scripts
Clean up migrated content
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 40,000) are viewed most often
• Provide analytics to prioritize work on content
Partner Report Card
Partner Activity Mark
1 Analyze content A+
Train writers in DITA
Train writers in XML and CMS tools
Assist with information model (pilot)
Assist implementation of CMS (pilot)
Create publication scripts
Create conversion scripts
Clean up migrated content
Our existing CMS did not meet our requirements. Core team found two CMS 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.
Books on DITA 1-week training class in DITA 3-day training class on the CMS 6-month pilot to develop information model and implement CMS
One partner (#2) helped trained writers in DITA and helped with the information model Individual writers conducted research projects in areas of interest (context-sensitive help, reuse strategy, cross-references, and so on.) CMS vendor (#3) helped with training and implementation of the CMS Writers devoted about 20% of their time to the pilot Writing team met weekly in conference call with partners
Partner Report Card
Partner Activity Mark
1 Analyze content A+
2 Train writers in DITA A+
3 Train writers in XML and CMS tools A-
2 Assist with information model (pilot) A-
3 Assist implementation of CMS (pilot) A+
Create publication scripts
Create conversion scripts
Clean up migrated content
Mark topics with DITA information type (task, concept, reference) in original CMS Inventory shared topics in original CMS Inventory shared graphics in original CMS Inventory instances of “conrefs” in original CMS
Old CMS
Export
Import to new CMS
DITA
Convert
XML
Staging Server
Production Server
Output
Publish
Transfer
Clean up
Some cleanup is always necessary The less “intelligent” the original content, the more manual cleanup will be necessary
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.
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.
Non-semantic (unintelligent) Semantic (intelligent)
<steps>
<step><cmd>Click the Alert button </cmd> <stepresult>The Create/Edit Alert dialog box appears. </stepresult> </step> <step><cmd>On the Create/Edit Alert dialog box, select the Enable check box. </cmd> <info>The Enable check box is located at the bottom of the dialog box.</info> </step> </steps>
Non-semantic (unintelligent) Semantic (intelligent)
<ol> <li>Click the Alert button. <p>The Create/Edit Alert dialog box appears. <p> </li> <li>On the Create/Edit Alert dialog box, select the Enable check box. <p>The Enable check box is located at the bottom of the dialog box</p> </li> </ol>
<steps> <step><cmd>Click the Alert button </cmd> <stepresult>The Create/Edit Alert dialog box appears. </stepresult> </step> <step><cmd>On the Create/Edit Alert dialog box, select the Enable check box. </cmd> <info>The Enable check box is located at the bottom of the dialog box.</info> </step> </steps>
Non-semantic (unintelligent) Semantic (intelligent)
<p> to ??
<ol> <li>Click the Alert button. <p>The Create/Edit Alert dialog box appears. <p> </li> <li>On the Create/Edit Alert dialog box, select the Enable check box. <p>The Enable check box is located at the bottom of the dialog box</p> </li> </ol>
<steps> <step><cmd>Click the Alert button </cmd> <stepresult>The Create/Edit Alert dialog box appears. </stepresult> </step> <step><cmd>On the Create/Edit Alert dialog box, select the Enable check box. </cmd> <info>The Enable check box is located at the bottom of the dialog box.</info> </step> </steps>
<p> to ??
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.
Partner Report Card
Partner Activity Mark
1 Analyze content A+
2 Train writers in DITA A+
3 Train writers in XML and CMS tools A-
2 Assist with information model (pilot) A-
3 Assist implementation of CMS (pilot) A+
Create publication scripts
Create conversion scripts
4 Clean up migrated content A+
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.
Partner Report Card
Partner Activity Mark
1 Analyze content A+
2 Train writers in DITA A+
3 Train writers in XML and CMS tools A-
2 Assist with information model (pilot) A-
3 Assist implementation of CMS (pilot) A+
Create publication scripts D Create conversion scripts F
4 Clean up migrated content A+
Partner Report Card
Partner Activity Mark
1 Analyze content A+
2 Train writers in DITA A+
3 Train writers in XML and CMS tools A-
2 Assist with information model (pilot) A-
3 Assist implementation of CMS (pilot) A+
2 Create publication scripts D 2 Create conversion scripts F 4 Clean up migrated content A+
Partner #2 Report Card
Partner Activity Mark
2 Train writers in DITA A+
2 Assist with information model (pilot) A-
2 Create publication scripts D
2 Create conversion scripts F
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. CMS 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!
When a partnership works, it saves time and prevents frustration. Go for a partner with experience in the areas where you need help. Hiring an inexperienced partner is a false economy. Even with the inexperienced partner, it was still worth it to get outside help.
• Beth Fryer, Timothy Martin, Dan Claessens • Faith Weber, Doug O’Neill
http://www.dclab.com/webinars/case-study-the-value-of-partnership-during-conversion
