@conref @conkeyref @conrefpush REUSE STRATEGIES IN DITA WHEN MIGRATING LEGACY CONTENT 1 2015 Conference
Feb 08, 2017
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
© Adam Sanyo, 2015 2015 Conference
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.
© Adam Sanyo, 2015 2015 Conference
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).
© Adam Sanyo, 2015 2015 Conference
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.
© Adam Sanyo, 2015 2015 Conference
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).
© Adam Sanyo, 2015 2015 Conference
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?).
© Adam Sanyo, 2015 2015 Conference
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.
© Adam Sanyo, 2015 2015 Conference
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.
© Adam Sanyo, 2015 2015 Conference
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
© Adam Sanyo, 2015 2015 Conference
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.
© Adam Sanyo, 2015 2015 Conference
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
© Adam Sanyo, 2015 2015 Conference
13Examples (in oXygen XML Author)
Using conditional processing (in a master topic) Using @conkeyrefs (on two maps) Using @conrefpush
© Adam Sanyo, 2015 2015 Conference
14Contact information
Adam Sanyoinfo@sanyowritingsolutions
.co.uk
© Adam Sanyo, 2015 2015 Conference
15If I timed myself right, we have 10 minutes for questions
Questions?