Implementing Content Reuse in DITA: The Nuts and Bolts

Presentation Transcript

Dan Dionne

UTS Technical Team Lead

IBM Silicon Valley Lab

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

Content reuse in DITA

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.