Implementing Content Reuse in DITA: The Nuts and Bolts

1
Implementing Content Reuse in DITA The Nuts and
Bolts

• Dan Dionne
• UTS Technical Team Lead
• IBM Silicon Valley Lab

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

3
Effective reuse of informationwhy we arent
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

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

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

6
Reuse problems and solutions

• Based on reuse experience from the IBM
  Information Management community
• Needs
• Technical solutions
• Best practices

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.

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
• ltph conref"../reuse/common.ditacommon/
  prodname/gt
• Clever trick Use the search path file to switch
  to a different common file for different outputs

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
  filespaghetti 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 tocno, printno,
  and linkingnone 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 (ltphgt) are the easiest elements to reuse,
  in almost any context

10
Demonstration element-level reuse
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

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)

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

14
Demonstration conditionality 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

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

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
• ltaudience experiencelevelexpert
  jobtroubleshooting typeprogrammer
• Use otherjob and othertype to create your own
  labels
• Prodinfo element includes sub-elements
• ltprodinfogtltprodnamegtMy productlt/prodnamegt
  ltvrmlistgtltvrm modification2 release3
  version5.0lt/vrmgtlt/vrmlistgtlt/prodinfogt
• Set build-time filters to build customized output
• Eventually, set run-time filters to display
  customized output

18
Demonstration filtering 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.

20
Demonstration combination topic with reused
topics
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. Its
  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

22
Demonstration map-level reuse
23
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