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

50 %
50 %
Information about Surviving the Transition to DITA: Trusted Partners can Ease the Pain

Published on September 29, 2015

Author: NickiDavis1

Source: slideshare.net

1. Nicki L Davis, PhD San Francisco STC nickinmr@gmail.com 19 August 2015

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

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

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

5. Darwin Information Typing Architecture XML Topic-based authoring 3 information types: task, concept, and reference Semantic markup: based on meaning, not formatting

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

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

8. *Mandatory element These elements come from the Darwin Information Typing Architecture (DITA) standard, but are not restricted to DITA. Topic element User question Context 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?

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

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

11. Partnership 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 CCMS (pilot) Create publication scripts Create conversion scripts Clean up migrated content

12. 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 10,000 - 20,000) are viewed most often • Provide analytics to prioritize work on content

13. Partnership Report Card Partner Activity Mark 1 Analyze content A Train writers in DITA Train writers in XML and CCMS tools Assist with information model (pilot) Assist implementation of CCMS (pilot) Create publication scripts Create conversion scripts Clean up migrated content

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

15. 1-week training class in DITA 3-day training class on the CCMS 6-month pilot to develop information model and implement CCMS Books on DITA

16. One partner (#2) helped train writers in DITA and helped with the information model CCMS vendor (#3) helped train writers on the CCMS and implement selected CCMS features Individual 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 pilot Writing team met weekly in conference call with partners

17. Partnership Report Card Partner Activity Mark 1 Analyze content A 2 Train writers in DITA A 3 Train writers in XML and CCMS tools A 2 Assist with information model (pilot) A 3 Assist implementation of CCMS (pilot) A Create publication scripts Create conversion scripts Clean up migrated content

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

19. 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. <p> to ?? <p> to ??

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

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

22. Original 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.

23. Partnership Report Card Partner Activity Mark 1 Analyze content A 2 Train writers in DITA A 3 Train writers in XML and CCMS tools A 2 Assist with information model (pilot) A 3 Assist implementation of CCMS (pilot) A 2 Create publication scripts D 2 Create conversion scripts F 4 Clean up migrated content A

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

25. When 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 scripts Even with the inexperienced partner, it was still worth it to get outside help.

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

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

Add a comment

Related pages

History: 2014 - East Bay STC Chapter in Northern California

Nicki Davis - Surviving the Transition to DITA: Trusted Partners Can Ease the Pain: November 2014 T.R. Girill - When School Standards Meet Literacy Outreach:
Read more

Events - DJCline.com

Here are some events you might want to attend. Check with the respective organizations for more information. Date: August 4th 12:00 to 1:30 PM
Read more

All | LavaCon 2013

Can you extend the value of DITA to other ... methodologies for improving reuse visibility to ease the ... documentation that was not trusted, ...
Read more

mooring Boats Under Construction - Alumarine

3 new mooring boats under construction 3 new mooring boats are currently under construction at the shipyard. One boat in 9-meter version will be delivered ...
Read more

bbfiles - Главная страница

Кто сейчас на конференции Онлайн: Bing [Bot] Всего пользователей: 16 Новый пользователь: ...
Read more

The forum gazette vol 2 no 7 april 5 19, 1987 by Sikh ...

... the ..Jj1ree months after a case was Presidednt's actions can signifi ... But underneath the pain ... Blit after opting to ease him out of ...
Read more

Senior Resource Guide Southeast Houston (Winter/Spring ...

... Senior Resource Guide Southeast Houston (Winter ... PREMIUM PARTNERS ... The WORLD LEADER in stairlifts The MOST TRUSTED name in the ...
Read more