This is the presentation I gave during the Soap! 2015 conference in Krakow.

1. @conref
@conkeyref
@conrefpush
REUSE STRATEGIES IN DITA WHEN MIGRATING LEGACY CONTENT
1
2015 Conference

2. © Adam Sanyo, 2015 2015 Conference
Agenda
 Why companies decide to adopt DITA?
 Planning the migration of legacy content
 How to reuse content in DITA
 Examples
2

3. © Adam Sanyo, 2015 2015 Conference
My background
 Five years of experience in technical writing.
 Worked on two different migration projects.
 Degree in English and Linguistics.
 Currently working for ARM as an information
developer on a contract basis.
 “Love at first sight” when encountering DITA in 2010.
3

4. © Adam Sanyo, 2015 2015 Conference
Why companies decide to adopt DITA?
Because they want to do any of the following:
 Reuse content across products.
 Reduce costs (for example, translation or authoring cost).
 Share workload between individual writers (increase productivity).
4

5. © Adam Sanyo, 2015 2015 Conference
DITA adoption scenarios
 The company wants to manage a large document set from a
component content management system (CCMS) and wants
to get rid of authoring silos.
 Different authoring teams create similar content and some of
that content could be reused.
 The company wants to translate its document set effectively
and wants to reuse translations over time.
5

6. © Adam Sanyo, 2015 2015 Conference
Strategy for legacy content migration
Note: I will not cover budget considerations (as I have never done that
part), but I will cover the technical side.
 Select part of your content as a test and see how you can reuse and
restructure it (run a prototype project).
 Have at least some rough reuse processes and guidelines.
 Write a good conversion script (that transforms legacy content to XML).
 Visualize your end product (the outcome of the project or a deliverable).
6

7. © Adam Sanyo, 2015 2015 Conference
Authoring decisions
Let us assume that you are using the standard DITA framework (task-
concept reference topics) and maybe one or two extra topic types on top of
that.
 Identify your topic types and chunk the content accordingly.
 Start with task topics as those are the easiest ones to identify but the
most difficult ones to convert (because of DITA-constraints in task topics).
 Select your reuse strategy after you analyzed your content.
 Decide the level of deviation from the original content (is your project a
simple conversion of your content or do you want to rework some parts of
the text?).
7

8. © Adam Sanyo, 2015 2015 Conference
Some general reuse rules
 Gain flexibility by using keys (because they create
a dependency only on the map level).
 Reuse block elements (paragraphs or elements
with similar size), but you can reuse smaller
elements if they do not require translation (for
example, product names or version numbers).
 Rewrite two or more similar topics if they become
reusable after that.
8

9. © Adam Sanyo, 2015 2015 Conference
Using @conref
Definition
 “Content reference”, that is, referencing one piece
of content from one topic to another.
Reuse strategy
 You want to reuse universal content found in
many or all publications.
Example
 Copyright information
Limitation
 Make sure that the referenced content is correct
in all publications where it is used, or you must
maintain different versions of the text.
1. Content is created in a reusable topic (“reusable_topic.dita”).
2. The topic id and the element id is used in the reference
(topic id: “reuse”, element id: “copyright”).
<p conref="reusable_topic.dita#reuse/copyright"/>
Output: © All rights reserved, 2015.
9

10. © Adam Sanyo, 2015 2015 Conference
Using @conkeyrefs
Definition
 “Content key reference”, which is an indirect
content reference governed by defined keys on the
map level.
Reuse strategy
 You have few differences between topics in your
product.
Example
 Changing elements between similar products
using keys (e.g. version numbers of products).
Limitation
 Managing the content on the map level using a
reference topic can become difficult and results in
too much overhead over time.
1. The key is defined on the map level with reference to a
topic that contains the content.
<keydef href= "reference.dita" keys="variables"/>
2. The key that is assigned to the topic and the id of the
referenced content is used for referencing content.
Reference to the topic: “variables”
Reference to the element id in the topic: “version”
<keyword conkeyref="variables/version"/>
Output: Version 15
10

11. © Adam Sanyo, 2015 2015 Conference
Using conditional processing/profiling (DITAVAL)
Definition
 As the name suggests, conditional values are defined to select
given parts of the full content. It is also called content profiling.
When to use
 Useful for authors when they create content for multiple audiences
 It is easier to manage attributes than keys (up to a certain point).
Example
 The same topic is sent to different clients, and some parts of the
text are client-specific.
Limitation
 It is better to store the content pieces in separate topics rather than
having a big master topic with all the content.
1. Define the DITAVAL attributes, for example, to exclude
a given version number.
<prop action="exclude" att="audience"
val="version15"/>
2. When generating your output, add this DITAVAL file to
your scenario and the output will not contain what you
excluded.
Note: As long as something is not excluded, it will be
included.
11

12. © Adam Sanyo, 2015 2015 Conference
Using @conrefpush
Definition
 Push some content before, in place of, or after a
marked section.
When to use
 It is recommended as a temporary solution only.
Limitation
 Compared to keys, it can be hard to manage many
conrefpush scenarios, and it is also harder to set
up conferpush scenarions for a novice DITA user.
1. Give an id to the element where your new content
would be in your content topic and use a conref to add
this selected element into your reference topic (the
topic that contains the new content you want to add).
2. Add the “mark” conaction attribute to the referenced
content.
3. Create the new content in the reference topic.
4. Add the reference topic with resource-only
outputclass attribute to your main content map.
More info: http://dita.xml.org/resource/dita-12-feature-
article-conref-push
12

13. © Adam Sanyo, 2015 2015 Conference
Examples (in oXygen XML Author)
 Using conditional processing (in a master topic)
 Using @conkeyrefs (on two maps)
 Using @conrefpush
13

14. © Adam Sanyo, 2015 2015 Conference
Contact information
14
Adam Sanyo
info@sanyowritingsolutions.co.uk

15. © Adam Sanyo, 2015 2015 Conference
If I timed myself right, we have 10 minutes for questions
Questions?
15