dita reuse challenges and response
TRANSCRIPT
![Page 1: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/1.jpg)
DITA Reuse Challenges and Responses
Moving from books to modular content without going mad
![Page 2: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/2.jpg)
About the Author
Founding and continuing member of the OASIS DITA Technical Committee
Co-editor of ISO/IEC 10744:1996, Hypertext Time-Based Markup Language (HyTime)
Founding member of the W3C XML Working Group
Author of DITA for Practitioners Volume 1: Architecture and Technology (XML Press)
Founder and principal contributor to the open source DITA for Publishers and DITA Community projects (both on GitHub)
![Page 3: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/3.jpg)
Agenda
A reuse story
Challenges
Why is reuse so challenging?
Reuse and linking
Reuse and configuration and information management
Meeting the reuse challenge
Managing links in reused content
Information management strategies
Where to go from here
![Page 4: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/4.jpg)
A Reuse Story
![Page 5: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/5.jpg)
You decide to move to DITA from your current system...
![Page 6: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/6.jpg)
You get a nice set of maps and topics...
![Page 7: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/7.jpg)
You produce new deliverables from DITA
![Page 8: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/8.jpg)
Flush with your success you start to create new publications that reuse existing topics...
![Page 9: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/9.jpg)
You try to publish PDF from the new publication and it fails with broken links
![Page 10: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/10.jpg)
What happened?
![Page 11: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/11.jpg)
Reuse Happened
Legacy content written as books in a book-focused way
Writers used lots of cross references to help readers navigate
Documents have only ever been published as PDF or maybe HTML produced from a DTP system
The legacy may have included cross-book links, which the non-DITA system could render because magic
Now you’re reusing the content in new publications and links break.
Why?
![Page 12: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/12.jpg)
Challenges Inherent in Reuse
![Page 13: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/13.jpg)
Reusing Topics With Links to Other Topics
If a topic has a link to another topic and you reuse the first topic in a new publication, the target topic must also be in the new publication or ...
...you make the link go to a different target in the new publication or…
...you make the link a cross-book link to the topic as published in its original location
How do you make any of these things happen in a manageable, interchangeable, and sustainable way? (Hint: keys)
![Page 14: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/14.jpg)
Reusing Topics Multiple Times in the Same Publication
If you use a topic two or more times in a publication and you link to that topic, which use of the topic you want the link to go to:
The first?
The last?
All of them?
If the reused topic has conditional content that should be filtered differently in different parts of the same publication, how do you do that? (hint: DITA 1.3 branch filtering)
![Page 15: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/15.jpg)
Reusing Elements With Embedded Links Within Topics
If you have a set of task steps that you want to reuse in other tasks and one of those steps includes a link to something else, what happens when you reuse that step?
How do you make the link do the right thing in all the places where its reused?
(Hint: DITA 1.3 “this topic” fragment identifiers, keys)
![Page 16: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/16.jpg)
Reacting to Changes to Reused Content
You’ve reused the same topic in several publications
The topic is updated, creating a new version of the topic
How do the documents that reuse the topic react?
Automatically use the new version?
Use the older version they were already using?
If the answer is “use the older version”, how do you do that?
What is the workflow for the authors of the reusing publications in this case?
![Page 17: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/17.jpg)
Managing Conditional Content in Reused Content
In a re-used topic you have content that is applicable to one condition or another (e.g., different operating systems or products or audiences)
How do you ensure that each publication or (with DITA 1.3) subpart of a publication applies the correct filtering and flagging conditions?
![Page 18: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/18.jpg)
Managing Review and Quality Assurance of Reused Content
Having authored publications with reused content, the publications must be reviewed and other quality assurance checks made (such as looking for broken links, appropriate formatting, etc.)
How do you manage reviews and quality assurance such that the reuse is appropriately validated and so that reviewers understand that reuse is happening (so they don’t make unhelpful suggestions)?
![Page 19: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/19.jpg)
Where Does This Leave Us?
Reuse provides definite benefits
But comes with unavoidable cost as well
Must understand the cost as well as the benefit
Can then determine the value to you of different kinds of reuseWhat costs more than it helps?
What practices can be eliminated or modified to make reuse less expensive?
What tools and practices need to be added to make reuse less expensive?
Do not fear reuse
Nor should you over value it
![Page 20: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/20.jpg)
Meeting Reuse Challenges
![Page 21: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/21.jpg)
Topic Reuse Use cases: Topics With Links
UC1: Same Topic Used in Two Publications
Pub 1 Map
Pub 2 Map Topic C
Topic A links to Topic B
UC2: Same Topic Used Twice in Same Publication
Pub 3 Map
Topic A
Topic B
Topicrefs
Topicrefs
![Page 22: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/22.jpg)
UC1: Topic Used in Two PublicationsIn Pub 2 what happens to the link
from Topic A to Topic B?
Three possible solutions:a. Include Topic B in Pub 2
b. Make link from Topic A a link to a different topic in Pub 2
c. In context of Pub 2 make link to Topic B a cross-book link to B in Pub 1
Requires use of keys
Option (c) requires DITA 1.3 cross-deliverable link feature
Pub 1 Map
Pub 2 Map Topic C
Topic A links to Topic B
Topic A
Topic B
Topicrefs
![Page 23: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/23.jpg)
UC2: Topic Used Twice in Same Publication
Topic B is used twice
Which use of Topic B should the link from Topic A go to?
a. The first one?
b. The second one?
c. Both?
Requires the use of keys on the topicrefs to Topic B
Topic A links to Topic B Pub 3
Map
Topic A
Topic B
Topicrefs
![Page 24: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/24.jpg)
Must Use Keys for Links from Topics
Direct URI references (@href, @conref) point to things outside of any use context
Create a hard dependency between the topic and the target
No way to dynamically modify the target when topic is used in different contexts
Solution is to use indirection: DITA keys and key references
Keys are defined in maps
Same key reference can be bound to different targets in different maps
![Page 25: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/25.jpg)
Keys to the Rescue: Use Case 1Use key reference on link from
Topic A:<xref keyref=”more-info”/>
Define key in each map (on the topicrefs to the appropriate targets)
In Pub 1: Topic A links to Topic B
In Pub 2: Topic A links to Topic C
Alternative (DITA 1.3): Make Pub 2 link to Topic B as used in Pub 1 (cross-deliverable link)
Pub 1 Map
Pub 2 Map Topic C
Topic A links to Topic B
Topic A
Topic B
Topicrefs
keys=”more-info”
keys=”more-info”
![Page 26: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/26.jpg)
Keys to the Rescue: Use Case 2
Use key reference on link from Topic A:<xref keyref=”more-info”/>
Set key “more-info” on the use of Topic B you want Topic A to link to (2nd use in this example)
Use intermediate topic to link to multiple uses of Topic B
Pub 3 Map
Topic A
Topic B
Topicrefs
keys=”more-info”
![Page 27: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/27.jpg)
Result: Topic A is completely reusable
Replacing direct URI reference (@href) on link from Topic A to Topic B with a key reference allows Topic A to be used in multiple contexts
Map authors control what the link from Topic A resolves to in their maps
Author of Topic A is stating a requirement: This topic requires that there be a topic or topics at the other end of this link.
Author of Topic A cannot control what will be at the other end of the link except through control of the maps that use Topic A
This is a significant change in writing practice and responsibility for most writers
![Page 28: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/28.jpg)
Additional Reuse Challenges
Reused content with conditional elementsMust set the conditions correctly when publishing the content
If topic is used multiple times in the same map, may need to apply different conditions in different parts of the (DITA 1.3 branch filtering)
Reuse of an individual element that contains a linkIf link is to a key, map authors need to ensure keys are set correctly
If link is to an ID within the same topic, need to ensure the target ID is present in each topic that uses the element
![Page 29: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/29.jpg)
Things You Can Use Keys For
Topics
Images
External resources (Web pages, PDFs, etc.)
Other root maps (DITA 1.3 cross-deliverable links)
Things used by DITA <object> elements (DITA 1.3)
Submaps (but don’t unless you know exactly what you’re doing)
![Page 30: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/30.jpg)
Reuse Information Management Challenges
Reacting to new versions of reused contentEach using context must be evaluated to see if new version is appropriate
Probably requires clear business rules and policies for what to use and how to react
May require more sophisticated configuration management of publications, e.g., using version control branching or carefully-controlled version-specific map
Reviewing and assuring quality of publications with reused content
Finding things to reuse
Defining and enforcing appropriate reuse policiesWhat should and should not be reused
How should the reuse be done
![Page 31: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/31.jpg)
Putting It All Together
![Page 32: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/32.jpg)
What Reuse Brings
DITA enables reuse and supports (almost) all reasonable use cases
Must understand the cost and benefit of the reuse DITA lets you do
Reuse adds complexity to your content
Requires more sophisticated information management, policies, and practices
Usually demands a new role in the writing organization, the Information Manager or Publication Configuration Manager
![Page 33: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/33.jpg)
Putting Reuse Into Practice
Start slow
Always use keys
Define appropriate policies as soon as possible: reuse policies, naming conventions, etc.
Identify people who can act as Information Architects or Configuration Managers
Plan for the extra up-front and Q/A effort reuse imposes
Always use keys
Choose your tools carefully
Always use keys
![Page 34: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/34.jpg)
Discussion
![Page 35: DITA Reuse Challenges and Response](https://reader035.vdocuments.mx/reader035/viewer/2022062822/587b24ef1a28ab736c8b75d9/html5/thumbnails/35.jpg)