Passport to DITA Implementation CIDM April 2017
1 like239 views
The document discusses strategies for efficient content migration and reuse in technical communication, emphasizing minimalism and organization of content types. It outlines two case studies focused on analyzing and normalizing content for optimal reuse, which can significantly reduce maintenance efforts. The document also highlights various methods for managing unique and shared content within the context of multi-product documentation.
Passport to DITA Implementation CIDM April 2017
- 1. May 2017
- 2. About the Speaker • 18 years in the tech comm domain • Based in Vancouver, Canada • Now in the Pre-sales team for Ixiasoft • sharon.figueira@ixiasoft.com Photo by Jerry Meaden. This work is licensed under a Creative Commons Attribution 2.0 License.
- 3. Now Voyager
- 4. Travel Light • Get rid of the baggage - follow the principles of minimalism • Select a cut over point: § Just the latest release § One or two products only § One content type § Run a Pilot
- 5. Identify Objectives • Prepare for migration? • Improve quality and consistency? • Find reuse efficiencies? • Minimalize content?
- 6. Look for Patterns • Find the biggest bucket - start with your largest category of documents • Subsections (submaps) • Topics • Elements
- 7. Not Always About the Tools • Genericize – use general terminology • Isolate • Normalize content – look for differences which are cosmetic or author preferences: • Decide not to reuse
- 9. Identify Blockers, Fail, Iterate • Mixed information types • Invalid DITA content • Mix of formatting and styles • Deeply nested hierarchies • Hard-to-identify topic types
- 10. Home or Away? • One-time migration tasks– do where it is easiest • Tasks with learning potential – treat as on-the-job training • BUT – keep the source close to the original so you can easily do quick QA on the migrated content
- 11. Case Study #1: Analysing Content for Efficient Migration
- 12. - Seven Install Guides - Three install workflows - Install routines for common components for each product
- 13. Installation Instruction (bookmap) Chapters provide a consistent hierarchy for each workflow and support usability/navigation. . Bookmaps reside in the product release version and pull shared content in submaps/topics from library release versions Submaps organize reused topics. Collections of topics are shared across installation bookmaps, topics are added, removed, or revised once and updated everywhere. Submaps for install workflows 2 and 3 reuse subsets of same topics from first workflow. RelTable resides in the bookmap for inter-topic linking. Introduction Overview Related Information (reused topic) General Prerequisites (reused chapter topic) First Install Workflow DB Prerequisites (submap) mapref Topicref Topicref Topicref Application Prereqs (app-specific submap) mapref Topicref Topicref Topicref Component Prereqs mapref Topicref Topicref Topicref Workflow2 and 3 DB Prerequisites mapref Topicref Topicref Unique installation content is included in the bookmap, in its own app-specific submap. Single reusable topics are referenced by each bookmap and revised once, updated everywhere. .
- 14. Content Analysis to Reduce Migration Effort 1. Identify topics and topic groups (submaps) that could be reused in the future CCMS environment 2. Document the content model 3. Pre-fabricate submaps in the CCMS 4. Migrate only unique content 5. Drag reused submaps/topics into the right location in the seven target guides Only the unique content was prepped, imported, and cleaned up, with massive time savings
- 15. • Reusing submaps represents a significant reduction in maintenance effort. • When you add or remove a topic, change is propagated across all guides. • Once we normalized content and genericized terms, reuse of the entire submap is blocked by just one table. • You can manage unique content in several ways – profile, conref, or keys. Find Reusable Content Flows (Submaps)
- 16. Use Conditions to Manage Unique Content in Shared Submaps • Topics which block reuse in a submap can be conditionalized • All bookmaps referencing the submap update automatically
- 17. Use Keys to Manage Unique Content in Shared Topics Key maps define how the keys are to be resolved in a given bookmap. Keymap referencing two keys • keys—Human-readable name that applies to both keys in the set (in this example, “install_cudb”). The same for each keydef regardless of product. • keyref—ID of the key (referable-content object). Each keydef points to a different object. Each keydef is addressed as follows:
- 18. Case Study #2: Analysing Content for Reuse
- 19. Reusing Topics - Strategies • Genericize: Is it possible to remove details such as product specifics without affecting usability? • Isolate: Is it possible to isolate diverging content in a specific document, map title, topic title? • Normalize: Is the content similar enough that you could rewrite it to be identical? • Separate: Can you separate diverging content into blocks and conditionalize and generate different flavors of a document (one for product A, one for product B)?
- 20. • Example 2: Change all variant titles to Create and Configure the LDAP User Remove Application-specific Terms Maximize reuse with generic references: Disconnect all electrical connections from the ABC board Disconnect all electrical connections from the XYZ board • Create and Configure LHR LDAP User • Create and Configure AME/PG LDAP User • RIE LDAP User • AME/PG LDAP User • Example 1: Refer generically to “the board”? (doc title identifies the product).
- 21. Normalize Diverging Content • Every instance must be updated, multiplying effort exponentially. • Graphics also may have diverged. • Creates a usability issue for the user. • Creates an issue for the writer – which one is correct? Initialize the System 1. Initialize the system by clicking Diagnostics > System> Initialize. Initialize the XYZ System 1. Go to Diagnostics. 2. Select System. 3. Choose Initialize from the drop- down menu 4. Click Go. 5. Wait for the initialization to complete.
- 22. Postcard From the Other Side
- 23. Manage Identical Headings • In a CCMS, topics are stand- alone • Duplicated titles make rapid retrieval harder • Disambiguate headings– one possible strategy
- 24. Review Stacked Empty Headings • Blank headings can be useful to create a hierarchy or enforce consistency • Consider how this works in a topic-based content model
- 25. Develop a Strategy for Managing Images
- 26. Reusing Elements • Notes and Warnings • Definitions • Steps • Store in maps for easy management, review and retrieval • Conref these single instances into multiple topics
- 27. Inline Elements • Inline tagging: § Improves consistency and usability § Save effort – writer doesn’t have to think about each button or dialog box • Tagging is semantic, not about formatting • If inline tagging is inconsistent, it will migrate inconsistently • Use the minimal amount of inline tagging
- 28. It’s Not Going to Be Perfect, But It Will Be Interesting • Keep analysing your content and looking for new opportunities • Go for the biggest chunks of reuse because that’s where you will find the biggest payback • Content structure is harder to change than retrofitting notes into conrefs • Doing the little pieces before the big ones can sometimes lead to rework • Sometimes you need an outside perspective
- 29. Questions