DITA and componentized information

1. DITA and componentized information Skyla Loomis

2. Goal of this presentation • Learn how to leverage DITA to integrate componentized information more efficiently and with an improved user experience.

3. Agenda • Componentized information architecture • Navigation and linking with ditamaps and relationship tables

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

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

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”

7. Working in a componentized world

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

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

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

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?

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

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

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>

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>

16. 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 Summary of anchors vs navref

17. Controlling automated links with ditamaps • Collection-type attribute on topicrefs • Family • Sequence • Linking attribute on topicrefs • None • Normal • Targetonly • Sourceonly

18. Example of targetonly and normal linking http://publib.boulder.ibm.com/infocenter/db2help/topic/com.ibm.db2.udb.db2_olap.doc/cmdcubemodel.htm

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

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”

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

22. Swimming in links • Links can come from four sources: • Ditamap navigation with collection-type • Ditamap reltables • Xrefs coded inside topics (inline links) • Related links inside topics • You can generate more links than you can keep track of • Best practices: • Never use related links inside topics • Use xrefs as little as possible. • Minimize use of collection-type inside navigation • Put every possible link in a reltable

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

24. 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) Scope = local

25. 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 Scope = peer

26. 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 Scope = external

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

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

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