Implementing Content Reuse in DITA: The Nuts and Bolts Dan Dionne UTS Technical Team Lead IBM...
-
Upload
william-fox -
Category
Documents
-
view
218 -
download
1
Transcript of Implementing Content Reuse in DITA: The Nuts and Bolts Dan Dionne UTS Technical Team Lead IBM...
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
Content reuse in DITA 3
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
Content reuse in DITA 4
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 5
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 6
Reuse problems and solutions Based on reuse experience from the IBM
Information Management community Needs Technical solutions Best practices
Content reuse in DITA 7
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 8
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 9
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 11
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 12
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)
Content reuse in DITA 13
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 15
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 16
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 17
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
Content reuse in DITA 19
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 21
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