Implementing content reuse in dita the nuts and bolts
Download
1 / 23

Implementing Content Reuse in DITA: The Nuts and Bolts - PowerPoint PPT Presentation


  • 336 Views
  • Uploaded on

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

loader
I am the owner, or an agent authorized to act on behalf of the owner, of the copyrighted work described.
capcha
Download Presentation

PowerPoint Slideshow about 'Implementing Content Reuse in DITA: The Nuts and Bolts' - Mia_John


An Image/Link below is provided (as is) to download presentation

Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author.While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server.


- - - - - - - - - - - - - - - - - - - - - - - - - - E N D - - - - - - - - - - - - - - - - - - - - - - - - - -
Presentation Transcript
Implementing content reuse in dita the nuts and bolts l.jpg

Implementing Content Reuse in DITA: The Nuts and Bolts

Dan Dionne

UTS Technical Team Lead

IBM Silicon Valley Lab


Agenda l.jpg
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 l.jpg
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


Barriers to reuse l.jpg
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


Dita is designed to enable reuse l.jpg
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


Reuse problems and solutions l.jpg
Reuse problems and solutions

  • Based on reuse experience from the IBM Information Management community

  • Needs

  • Technical solutions

  • Best practices

Content reuse in DITA


Element level reuse l.jpg
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


Dita solution content referencing l.jpg
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


Content referencing best practices l.jpg
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


Demonstration element level reuse l.jpg
Demonstration: element-level reuse

Content reuse in DITA


Conditionality l.jpg
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


Dita and conditionality l.jpg
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


Conditionality inside topics l.jpg
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


Demonstration conditionality in dita l.jpg
Demonstration: conditionality in DITA

Content reuse in DITA


Topic level reuse l.jpg
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


Reusing a topic in multiple ditamaps l.jpg
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


Include topics in multiple ditamaps with filtering l.jpg
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


Demonstration filtering in dita l.jpg
Demonstration: filtering in DITA

Content reuse in DITA


Imbed topics inside combination topics l.jpg
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


Demonstration combination topic with reused topics l.jpg
Demonstration: combination topic with reused topics

Content reuse in DITA


Map level reuse l.jpg
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


Demonstration map level reuse l.jpg
Demonstration: map-level reuse

Content reuse in DITA


Summary l.jpg
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


ad