DITA and componentized information

honorableclunkSoftware and s/w Development

Oct 30, 2013 (4 years and 14 days ago)

122 views

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

© 2005 IBM Corporation

3

Agenda


Componentized information architecture


Navigation and linking with ditamaps and
relationship tables




IBM User Technology

© 2005 IBM Corporation

4

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

© 2005 IBM Corporation

5

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

© 2005 IBM Corporation

6

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

© 2005 IBM Corporation

7


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

© 2005 IBM Corporation

8

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

© 2005 IBM Corporation

9

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

© 2005 IBM Corporation

10

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

© 2005 IBM Corporation

11

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

© 2005 IBM Corporation

12

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

© 2005 IBM Corporation

13

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

© 2005 IBM Corporation

14

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

© 2005 IBM Corporation

15

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

© 2005 IBM Corporation

16

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

© 2005 IBM Corporation

17

Controlling automated links with ditamaps


Collection
-
type attribute on topicrefs


Family


Sequence


Linking attribute on topicrefs


None


Normal


Targetonly


Sourceonly


IBM User Technology

© 2005 IBM Corporation

18

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

© 2005 IBM Corporation

19

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

© 2005 IBM Corporation

20

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

© 2005 IBM Corporation

21

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

© 2005 IBM Corporation

22

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

© 2005 IBM Corporation

23

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

© 2005 IBM Corporation

24

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

© 2005 IBM Corporation

25

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

© 2005 IBM Corporation

26

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

© 2005 IBM Corporation

27

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

© 2005 IBM Corporation

28

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

© 2005 IBM Corporation

29

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