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 BenefitsChallengesTactical solution Strategic solution ReuseCoordinationCommunicationContent management system ConsistencyGeneralization 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.xmldesigning.xml –Child: cv_designing.ditamapcv_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  Child ditamap...

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  Child ditamap...

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

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.ditamapcv_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 or 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 or 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