Implementing Content Reuse in DITA: The Nuts and Bolts Dan Dionne

Implementing Content Reuse
in DITA: The Nuts and Bolts
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
2
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 nontechnical content
Effective reuse of technical content remains
elusive
Content reuse in DITA
3
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
Content reuse in DITA
4
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
Content reuse in DITA
5
Reuse problems and solutions




Based on reuse experience from the IBM
Information Management community
Needs
Technical solutions
Best practices
Content reuse in DITA
6
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.
Content reuse in DITA
7
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 reuse in DITA
8
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
Content reuse in DITA
9
Demonstration:
element-level reuse
Content reuse in DITA
10
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
Content reuse in DITA
11
DITA and conditionality

Basic conditional coding is the same for DITA
as for other SGML and XML


Multiple axes of conditionality available


Restriction: no Boolean logic for conditions; can
include multiple conditions, but relationship is a
simple OR
Audience, platform, product, and otherprops
attributes
Filtering metadata also at the topic level
(more later)
Content reuse in DITA
12
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
Content reuse in DITA
13
Demonstration:
conditionality in DITA
Content reuse in DITA
14
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
Content reuse in DITA
15
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
Content reuse in DITA
16
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


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


Best practice: always one or the other, never both. Experience suggests
that the topic prolog is best overall
<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
Content reuse in DITA
17
Demonstration:
filtering in DITA
Content reuse in DITA
18
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.
Content reuse in DITA
19
Demonstration:
combination topic with reused topics
Content reuse in DITA
20
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
Content reuse in DITA
21
Demonstration:
map-level reuse
Content reuse in DITA
22
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
Content reuse in DITA
23