DITA Reuse Challenges and Responses Moving from books to modular content without going mad
Welcome message from author
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
DITA Reuse Challenges and Responses
Moving from books to modular content without going mad
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)
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
A Reuse Story
You decide to move to DITA from your current system...
You get a nice set of maps and topics...
You produce new deliverables from DITA
Flush with your success you start to create new publications that reuse existing topics...
You try to publish PDF from the new publication and it fails with broken links
What happened?
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?
Challenges Inherent in Reuse
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)
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)
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)
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?
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?
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)?
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
Meeting Reuse Challenges
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
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
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
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
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”
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”
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
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
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)
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
Putting It All Together
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
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
Discussion
Related Documents
