The transition from unstructured to structured content can be daunting. A good working relationship with a trusted partner can work wonders to make the process easier for the writing team and save time.

1. Nicki L Davis, PhD nickinmr@gmail.com
STC Berkeley
9 July 2014

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

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

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

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

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

10. •
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

11. 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

13. 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

14. 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

16. 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.

17. 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

18. 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

19. 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

21. 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

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

23. Some cleanup is always necessary
The less “intelligent” the original content, the more manual cleanup will be necessary

24. 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.

25. 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.

26. 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>

27. 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>

28. 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 ??

29. 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.

30. 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+

31. 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.

32. 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+

33. 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+

34. 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

36. 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!

37. 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.

38. •
Beth Fryer, Timothy Martin, Dan Claessens
•
Faith Weber, Doug O’Neill
http://www.dclab.com/webinars/case-study-the-value- of-partnership-during-conversion