This document discusses challenges and responses related to moving from book-based content to modular content reuse in DITA. It outlines various reuse scenarios that can cause issues like broken links, and explains how keys can be used to manage links when content is reused in different publications or multiple times within a publication. The document also addresses challenges of managing conditional content, reviews, and changes when reusing content. It emphasizes that while reuse provides benefits, it also increases complexity and requires careful information management and policies.

1. DITA Reuse Challenges and
Responses
Moving from books to modular content without going mad

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

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

4. A Reuse Story

5. You decide to move to DITA from your
current system...

6. You get a nice set of maps and topics...

7. You produce new deliverables from DITA

8. Flush with your success you start to create
new publications that reuse existing topics...

9. You try to publish PDF from the new
publication and it fails with broken links

10. What happened?

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

12. Challenges Inherent in Reuse

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

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

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

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

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

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

19. 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 reuse
What costs more than it helps?
What practices can be eliminated or modified to make reuse less expensive?

20. Meeting Reuse Challenges

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

22. UC1: Topic Used in Two Publications
In 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
Pub 1
Map
Pub 2
Map Topic C
Topic A links
to Topic B
Topic A
Topic B
Topicrefs

23. 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
Topic A links
to Topic B Pub 3
Map
Topic A
Topic B
Topicrefs

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

25. Keys to the Rescue: Use Case 1
Use 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
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”

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

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

28. Additional Reuse Challenges
Reused content with conditional elements
Must 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 link
If 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

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

30. Reuse Information Management Challenges
Reacting to new versions of reused content
Each 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

31. Putting It All Together

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

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

34. Discussion