IBM User Technology © 2005 IBM Corporation DITA and componentized information Skyla Loomis.

IBM User Technology

© 2005 IBM Corporation

DITA and componentized information

Skyla Loomis

IBM User Technology

© 2005 IBM Corporation 2

Goal of this presentation

Learn how to leverage DITA to integrate componentized information more efficiently and with an improved user experience.

IBM User Technology


Agenda

Componentized information architecture

Navigation and linking with ditamaps and relationship tables

IBM User Technology


Assumptions

You are following a good, robust information architecture (IA) process, including

– User and task analysis

– Information modeling

Your information is chunked (what we, at IBM, call “topic-based”)

You face many information development challenges

– Doing more (information development) with less (resources)

– You have few IA resources—people consciously performing an IA role

IBM User Technology


Componentization: Why do we care?

Flexibility

– To reuse information -- without rewriting it

– To update information easily and often

– To integrate information -- across solutions and products, in multiple contexts

– To ship information to translation in a wider variety of configurations, allowing more flexibility at the end of the cycle

– To provide users with only what they need, not the entire library

Runtime plug-in management and link management depend on a componentized information architecture

Products and technologies are being componentized

IBM User Technology


Componentization

A component of information is “the largest group of topics that won't ever be split apart as a result of remarketing, repackaging, technological componentization, user tasks, or scenarios”

IBM User Technology


Working in a componentized world

Benefits Challenges Tactical solution

Strategic solution

Reuse Coordination Communication Content management system

Consistency Generalization of information

Conditional coding and related links

Shared translation memory

Translation shipment coordination

Reship topics with each set of consuming ditamaps

Improvements to translation process

IBM User Technology


Information strategy

Topic-based information architecture

Information owners identify reusable information components

– For development teams that are already componentizing, the information components should align with development

– For development teams that are not yet componentizing, the information units should be driven by groupings of task topics and their related concept and reference topics

Information consumers control ditamaps and relationship tables

IBM User Technology


Information owners vs consumers

Owners – Author raw topics with appropriate conditional coding

– Provide a shared content reference file

– Provide a readme for consumers of their information components

– Ensure accessibility

– Translate the information to provide a shared translation memory

– Optional: provide a recommended starter relationship table (includes related links only within the component)

Consumers– Review topic content

– Levy content requirements to owners

– Own ditamaps and reltables (can start with the recommended reltable, if provided)

– Usually must transform topics

– Ship to translation with specific transformation instructions, referencing the shared memory

IBM User Technology


Delivery: Eclipse information centers

Eclipse is an open source, extensible development platform and application framework for building software

Uses a plugin architecture

– Plugins are intended to be a reusable, extensible unit of code

– Typically represent a fully functional component, often from the end user’s perspective

Includes information center functionality

IBM User Technology


Information center plugin architecture

One plugin could equal one component, or could be a combination of components

– How many plugins should you deliver?

– Do your plugins have dependencies on other plugins that you or someone else owns?

– How many navigational ditamaps will you need for each plugin?

– How will you manage your related links between topics within a plugin and across plugins?

IBM User Technology


Controlling navigation with ditamaps

Use ditamaps to control navigation within a component

Rule of thumb: one ditamap per integration point

Example:

– Parent: designing.xml

– Child: cv_designing.ditamap

IBM User Technology


Integrating navigation with anchors vs navrefs

Both are used for runtime integration of navigation

Difference is in whether the parent or child ditamap does the referencing

– With anchors, the child ditamap references the location of the parent

– With navrefs, the parent ditamap references the location of the child

IBM User Technology


Anchors

Use anchors if the parent doesn’t know about what is being pulled in

For example, DB2 used anchors to pull in DB2 Cube Views content

Parent ditamap <toc label="Designing">

<topic label="Business intelligence"> <anchor id="bcu" /> <anchor id="cv" /> </topic></toc>

Child ditamap<map anchorref="../com.ibm.db2.udb.doc/planning.xml#cv" title="Designing">

<topicref href="gmdintro.dita" navtitle="DB2 Cube Views"> ... </topicref>

</map>

IBM User Technology


Navrefs

Use navrefs if you are the information owner and you are being used in many places

Parent ditamap <toc label="Designing">

<topic label="Business intelligence"> <navref mapref="../com.ibm.db2.udb.cv/cv_installing.ditamap"/> </topic></toc>

Child ditamap <map title=“Installing">

<topicref href="ginstallintro.dita" navtitle="DB2 Cube Views"> ... </topicref>

</map>

IBM User Technology


Summary of anchors vs navref

Use anchors if…

– The names of your ditamaps are volatile or are not controlled by the owner of the parent navigation

– The parent navigation is complex and integrates many, many components

– The parent navigation ships to translation earlier than the child information components

Use navrefs if…

– The names of ditamaps are controlled by the owner of the parent navigation

– The child information components are being reused in multiple places (synchronizing anchor IDs would be very complex)

– The child ditamap structure is final when the parent navigation ships to translation

IBM User Technology


Controlling automated links with ditamaps

Collection-type attribute on topicrefs

– Family

– Sequence

Linking attribute on topicrefs

– None

– Normal

– Targetonly

– Sourceonly

IBM User Technology


Example of targetonly and normal linking

http://publib.boulder.ibm.com/infocenter/db2help/topic/com.ibm.db2.udb.db2_olap.doc/cmdcubemodel.htm

IBM User Technology


Example of sourceonly and normal linking

Sourceonly would only be used when you want to be able to create relationships from a piece of information, but not to it

Introductory generic topics are the best candidates. Also “glue” topics that will only appear in PDF.

We couldn’t find any real-life examples

Best thought of as a safety valve to prevent unwanted links from coming in from another source

IBM User Technology


Linking and conref files

If you have a reuse file (conref file), it should be included in one of your ditamaps

But you never want to link to or from it, or to have it print or be included in the table of contents

Put it at the end of your ditamap, with print=“no”, toc=“no”, and linking = “none”

IBM User Technology


Controlling related links with relationship tables

One approach:

– Create a reltable for linking within each standalone component

– Create additional reltables to handle cross-component linking (number of additional tables depends on reuse plans and complexity of dependencies)

Example: cv_reltable.ditamap

IBM User Technology


Swimming in links

Links can come from four sources:

1. Ditamap navigation with collection-type

2. Ditamap reltables

3. Xrefs coded inside topics (inline links)

4. Related links inside topics

You can generate more links than you can keep track of

Best practices:

1. Never use related links inside topics

2. Use xrefs as little as possible.

3. Minimize use of collection-type inside navigation

4. Put every possible link in a reltable

IBM User Technology


Linking to topics outside of your information component

You can reference topics through topicrefs or xrefs that are not in your information unit

Use the scope attribute to identify the relationship between the current topic and the target resource

– Local

– Peer

– External

IBM User Technology


Scope = local

When to use

– If the topics are part of the same information unit

– If the target is outside of the delivery mechanism and you do not want the target to launch in a separate window

– For example, you can pull PDFs into your information center that do not launch in a separate window by setting the scope to local

Notes

– This is the default setting

– Use the local setting only if the target topic is part of the same information unit for translation (even if multiple IUs are built together)

IBM User Technology


Scope = peer

When to use– If the topics are

not part of the same information unit, but have the same delivery mechanism

Notes

– Verify that the target will be available when the files are delivered together, otherwise, you might have a broken link

– Use the peer scope to meet early translation testing deadlines for online help

– Add link text to the navtitle attribute of the <xref> or <topicref> element

• When the link references a DITA source, the navtitle will be used for the link text if you do not type additional link text

• When the link references a non-DITA source (PDF, HTML, etc.), you need to type in additional link text

IBM User Technology


Scope = external

When to use– If the target is

outside of the delivery mechanism and you want the target to launch in a separate window

Notes

– Add link text within the navtitle attribute of the <xref> or <topicref> element

• When the link references a DITA source, the navtitle will be used for the link text if you do not type additional link text

• When the link references a non-DITA source (PDF, HTML, etc.), you need to type in additional link text

IBM User Technology


Examples of scope settings

Inline link to another topic within the same information unit

Inline link to another topic that is in the same information center but is shared with another writer who is still working on it

Inline link to an external website

Link to a DITA topic from the ditamap that is part of the same information center but belongs to a different information unit

IBM User Technology


More examples of scope settings

Link to an external PDF (that you do not want to include in your information center) from the ditamap

Link to an external PDF (that you do want to pull into your information center) from the ditamap

IBM User Technology


Summary

Follow good information architecture practices

Componentize your information for greater flexibility and reuse potential

Use anchors and navrefs in ditamaps to easily integrate components

Manage linking dependencies carefully—you don’t want to break your reuse model

IBM User Technology © 2005 IBM Corporation DITA and componentized information Skyla Loomis.

Documents

Transcript of IBM User Technology © 2005 IBM Corporation DITA and componentized information Skyla Loomis.