Implementing Content Reuse in DITA: The Nuts and Bolts Dan Dionne UTS Technical Team Lead IBM Silicon Valley Lab

Implementing Content Reuse in DITA: The Nuts and Bolts

Dan Dionne

UTS Technical Team Lead

IBM Silicon Valley Lab

Content reuse in DITA 2

Agenda

Effective reuse of information Barriers to reuse DITA designed for reuse

Reuse problems and solutions Element-level reuse Conditional reuse Topic-level reuse Map-level reuse


Effective reuse of information—why we aren’t there yet Duplicate maintenance of information is

expensive Authoring time Maintenance! Consistency

Boilerplate reuse a general practice for non-technical content

Effective reuse of technical content remains elusive


Barriers to reuse

Unstructured authoring technologies are unsuitable for reuse Even structured authoring technologies (SGML) throw up many

obstacles Team communication issues. The smaller the scope, the easier.

Inconsistent and contradictory use of conditionality and other attributes

Information too thoroughly imbedded in a hierarchy Information is written in a larger context, such as a chapter How to break out reusable chunks?

Linking issues What do you link to? How do you maintain hard-coded links?

External dependencies Entities of all kinds Book-metaphor structures


DITA is designed to enable reuse Information design

Modular topics are complete in themselves Typed topics promote consistency of information

coverage Technical design

Elimination of most external dependencies, with improved management of the dependencies that remain

Flexible link management through ditamaps eliminates hard-coding of links


Reuse problems and solutions Based on reuse experience from the IBM

Information Management community Needs Technical solutions Best practices


Element-level reuse

Problem: Teams need to reuse information at the most granular level (paragraphs, phrases, notes)

In SGML, we created text entities for this sort of information !ENTITY prodname “Name of the product this

week” Worked well at the book and library level, but was

a disaster when integrating information across product boundaries.


DITA solution: content referencing Any element can be a pointer to another

element in another file by using the conref attribute

The reference includes a relative pathname if needed <ph conref="../reuse/common.dita#common/

prodname/> Clever trick: Use the search path file to switch

to a different common file for different outputs


Content referencing best practices Content referencing outside the file creates an external

dependency. Any element in any file can reference any matching element in any other file—spaghetti code!

To simplify dependencies, create a single mixed/combination topic for all reusable information in your information set Use a combination topic because it will allow you to create as

many of the typed topics as you need, all in one location Give the combination topic an obvious name You must include the content referencing topic in your ditamap.

But set it to toc=no, print=no, and linking=none so it never appears to the end users

Typing in the full conref string is error-prone. Use linking tools in your editor or create macros to insert the content references

Phrases (<ph>) are the easiest elements to reuse, in almost any context


Demonstration: element-level reuse


Conditionality

Problem: Near-identical information can be used in multiple situations.

Solution: Conditional coding Problem: Need to differentiate conditions in

the output Solution: Conditional coding with flagging


DITA and conditionality

Basic conditional coding is the same for DITA as for other SGML and XML Restriction: no Boolean logic for conditions; can

include multiple conditions, but relationship is a simple OR

Multiple axes of conditionality available Audience, platform, product, and otherprops

attributes Filtering metadata also at the topic level

(more later)


Conditionality inside topics

Audience, platform, product, and otherprops attributes available No fixed values Best practice: use same values as filtering elements Best practice: use semantically useful values

In run-time ditaval file, can set each value to include, exclude, or flag The default is include

Best practice: teams should share values Best practice: check your spelling! The system will not tell you when

you have an undefined value Flag associates an image with the value Best practice: use multiple ditaval files with semantically useful

names


Demonstration: conditionality in DITA


Topic-level reuse

Problem: entire topics need to be reused in different venues

Solution 1: include the topic in multiple ditamaps

Solution 2: include the topic in multiple ditamaps, but activate filtering

Solution 3: reuse the topic inside a combination topic


Reusing a topic in multiple ditamaps This is the whole point of ditamaps and modular topics A topic can be inserted in any ditamap as long as the pathing is

clear Simple relative paths are best, but the system can handle more

complex situations with search paths Verify that conditions and revisions are consistently defined

External dependencies need to be accommodated Reuse files need to be inserted in the ditamap as well Inline links may break

Best practice: never code inline links (use maps and relationship tables for all linking except to known external targets)

Graphics are handled by reference, so make sure they are available as well


Include topics in multiple ditamaps with filtering If the topics need to vary depending on their context, include filtering in

the metadata Metadata can be in the topic prolog or the ditamap

Best practice: always one or the other, never both. Experience suggests that the topic prolog is best overall

Audience element includes Experiencelevel, job, otherjob, type, othertype, name <audience experiencelevel=“expert” job=“troubleshooting”

type=“programmer” Use “otherjob” and “othertype” to create your own labels

Prodinfo element includes sub-elements <prodinfo><prodname>My product</prodname> <vrmlist><vrm

modification=“2” release=“3” version=“5.0</vrm></vrmlist></prodinfo> Set build-time filters to build customized output Eventually, set run-time filters to display customized output


Demonstration: filtering in DITA


Imbed topics inside combination topics A mixed/combination topic can contain any number or

combination of any other topic types in any order A combination topic is output as a single XHTML page

The title is the title of the first topic in the set Caveat: users may not know to scroll through a long combination

topic Topics can be authored exclusively in combination topics, but

more often are pulled into special-purpose combination topics to serve a dual purpose

Tutorial example Useful tip: if you have information that needs to be broken up into

multiple topics of different types, create a combination topic and create new topics in it as needed. Then save each topic out to a separate file.


Demonstration: combination topic with

reused topics


Map-level reuse

The highest level of reuse is achieved through architecting and reusing entire maps

Any number of maps can be imbedded in a map Pathing is the only real technical issue. It’s best to have a central

repository where all the maps and topics will come together The hard part is information design

Set map scope at appropriate levels “book” level maps are too high a scope “chapter” level maps work better Relationship tables can cross scope boundaries

Design maps according to the information design Each map should represent a distinct point in the navigation An information architect should manage the top levels of the map


Demonstration: map-level reuse


Summary

DITA solves or eases many of the technical problems associated with reuse Element-level reuse Conditionality Topic-level reuse Map-level reuse

Communication between teams remains critical

Good information design is the most important aspect of all

Documents

Implementing Content Reuse in DITA: The Nuts and Bolts Dan Dionne UTS Technical Team Lead IBM Silicon Valley Lab