"Conref, conkeyref, conrefpush" - reuse strategies in DITA when migrating legacy content

1

@conref@conkeyref

@conrefpushREUSE STRATEGIES IN DITA WHEN MIGRATING LEGACY CONTENT

2015 Conference

© Adam Sanyo, 2015 2015 Conference

2Agenda

Why companies decide to adopt DITA? Planning the migration of legacy content

How to reuse content in DITA Examples


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


4Why 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).


5DITA 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.


6Strategy 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).


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


8Some 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.


9Using @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 informationLimitation 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.


10Using @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


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


12Using @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

http://dita.xml.org/resource/dita-12-feature-article-conref-push




13Examples (in oXygen XML Author)

Using conditional processing (in a master topic) Using @conkeyrefs (on two maps) Using @conrefpush


14Contact information

Adam Sanyoinfo@sanyowritingsolutions

.co.uk


15If I timed myself right, we have 10 minutes for questions

Questions?

Technology

"Conref, conkeyref, conrefpush" - reuse strategies in DITA when migrating legacy content