Using DITA’s Flexibility to Assemble Information Components into Solutions
Markets change instantly. The launch of a new product or solution package by one company demands an immediate response from competitive companies. Product development teams are expected to deliver flexible offerings, which can easily be provided in different product or solution packages, as market needs change.
As part of the product development team, information developers are expected to provide flexible, dynamic information that can easily adapt to new demands. To do this, we can use one of the techniques that software-development teams use: component-based architectures.
Creating a well-thought out strategy for your components can help you avoid certain pitfalls and complete a successful project. The following sections will teach you how to begin working as information producers and consumers on a component-based information project and how to use DITA anchors, navrefs, and maps to integrate your information components.
The recommendations below are a result of work carried out by numerous information-development teams at IBM over the last several years, as well as feedback from DITA advocates and information practitioners working with component-based information architectures. It is by no means the “final word” on the subject but a starting point to help you think about one way to leverage components and DITA in your projects.
For the purpose of this article, an information component is simply a group of topics that always “travel” together. More formally, it is a group of topics that will not be split apart as a result of marketing, packaging, technological componentization, user tasks, or scenarios.
An information component can be reused and repackaged in different ways without requiring re-architecture of its topics and, ideally, without losing the meaning or the integrity of the information. All of the topics in a single information component are used in the same set of information deliverables. One deliverable is made up of any number of information components.
As always, a strong topic-based, user-goal-oriented information architecture is assumed.
In this example, Product A is the primary delivery vehicle for a set of data modeling features. Some of the features of Product A will also be delivered in other products. Most of those “consumer” products, products that will use Product A, will not consume Product A in its entirety. Therefore, the information set that belongs to Product A must be componentized at the lowest level of user tasks and features that will never be separated. For example, Product A must document its import capability and its search capability as separate, stand-alone components because the consuming teams might use one, both, or neither of these functions. In this way, the information development teams for the consumer products can reuse the componentized information for only those sets of Product A’s features that their consuming product exposes to their users.
Information Producers and Consumers
At the beginning of your information-development project, identify the producers and consumers of information components. Information producers and consumers are typically members of different information-development teams, but their information will be provided as an integrated solution to customers. Information producers and consumers have different tasks throughout the componentization project, but excellent communication between these teams is crucial to the success of a componentization project. In some cases, a single team may be both a producer of information for one set of solutions and a consumer of information in other solutions.
Information producers develop information that is going to be used by another team as part of a larger information deliverable or information set.
To begin, information producers analyze the needs of all of their consuming products or solutions. They look at how their technology and information will be packaged in those products or solutions. They look at what information can be reused, as well as what information will need to be different. They use that analysis to define a set of information components that will enable them to meet the needs of their various consumers.
For component-based software projects, the information components sometimes can align with software components. The information components also can be driven by groupings of task topics and their related concept and reference topics. Both approaches can be combined in one information set.
During development, information producers are responsible for the following tasks:
- authoring topics with appropriate conditional coding
- authoring DITA maps, relationship tables, and ditaval files for their information components
- providing a shared reuse file
- providing a readme for consumers of their information components
- ensuring accessibility
- providing the information to translation centers so translation memory can be established and used by all consuming products
- providing any component-specific build files
Information consumers are responsible for integrating information from multiple sources to create a cohesive information experience for their customers. They control the organization and navigation of the components within their larger set of information. At a tactical level, this means that they control the high-level DITA maps and relationship tables.
Information consumers are usually responsible for the following tasks:
- reviewing the topic content in the information component
- authoring DITA maps and reltables for the larger information set
- creating “glue” topics that fill any gaps or that streamline the integration of the component information into the larger deliverable
- merging component ditaval entries into the consuming product ditaval
- merging component XSLT templates into the product XSLT where appropriate
- transforming topics
- shipping to translation with specific transformation instructions, referencing the shared translation memory
Controlling Navigation with DITA Maps
The following discussion assumes that the information is being delivered in an Eclipse help system or any other technology that allows runtime integration of plug-ins. The Eclipse help system is a part of the Eclipse project by the Eclipse Foundation (www.eclipse.org). It is part of an open-source, extensible development platform and application framework for building software. The Eclipse help system can be used as part of an Eclipse application or as a stand-alone help system for other applications.
Eclipse uses a plug-in architecture that allows documentation plug-ins to be installed or updated at different times while providing integrated navigation and search across those plug-ins. From the end user’s point of view, Eclipse provides a single help system or “information center.” From the information developer’s point of view, the underlying information can be developed as multiple help plug-ins.
Together, DITA and Eclipse are a powerful combination for building a cross-product information center. In this situation, you can have multiple documentation groups that contribute information for several different products, with each group maintaining control of its own source files and DITA maps. The team that owns the overall navigation of the information center comes to an agreement with the teams for individual products about where the product content will appear, but the overall navigation team does not need to have access to the source files or ditamaps from the contributing product teams. The lower levels of the navigation are defined by the contributing product teams.
Being able to create a dynamic cross-product information center means that you can:
- provide integrated documentation for products that are distributed separately and even on slightly different schedules. During installation, each product can detect the information center and add its documentation plug-ins.
- provide customized documentation for suites of products. You can choose to install only those documentation plug-ins that correspond to the features that will be used by a particular customer.
In both of these situations, Eclipse simply does not display navigation for plug-ins that are not installed.
In this type of situation, you can:
- plan your navigation scheme ahead of time during development
- actively integrate plug-ins at runtime
- avoid build errors; if a plug-in is not there, it will simply not appear
- relinquish control of the source files and maps of the information units that feed into your larger offering
DITA maps enable you to control the navigation (table of contents) within a single component (or “plug-in” in the previous Eclipse example) and between components. In general, use one DITA map for each integration point. For example, in Figure 1, DB2® Cube ViewsTM component is integrated under the Designing category of the DB2® Universal Database (UDB) Information Center.
Figure 1. The DB2 UDB Information Center navigation*
*All graphics show DITA within the Arbortext Epic Editor with IBM customizations
Figure 2. Anchor tagging in a parent DITA map
In this case, the Designing category is controlled by a parent DITA map named designing.ditamap, and the DB2 Cube Views component is controlled by a child DITA map named cv_designing.ditamap. The child DITA map determines the relative organization of topics about designing. The parent DITA map determines the final placement of the group of topics (component) about designing. The parent DITA map can integrate the child DITA map where it is needed, but it cannot change the internal organization of the child DITA map.
How To Integrate Your Navigation by Using Anchors and navrefs
You can integrate complex navigation systems that span multiple components by using anchors and navrefs.
When to use anchors
You should use anchors if the parent DITA map does not control what is being included. Using anchors is especially beneficial where components are published on a different schedule than the consuming information set. When the component plug-in is published, its topics automatically appear at the anchor point in the consuming plug-in; before the publish date, the consuming plug-in shows no sign of the component plug-in.
For example, the DB2 UDB information center uses anchors to integrate the DB2 Cube Views content into the overall information center navigation. The parent DITA map includes an anchor tag with a specific ID that is assigned to the DB2 Cube Views information, cv. Figure 2 illustrates the DITA tagging for the parent DITA map in this example.
The overall information center DITA map contains specific IDs for all of its components, or contributing content, and, therefore, the architect for that large deliverable does not have to track down the details for all of the contributing components.
The child or component DITA map, must include an anchorref back to the parent DITA map that includes its specific ID. In other words, the DB2 Cube Views information producer must code the relative path to the parent DITA map plug-in and ensure that they have included the assigned ID. The information producers of the child DITA maps, or components, must be aware of their specific IDs and know how to code them as anchorrefs that refer back to the parent DITA map. Figure 3 illustrates the DITA tagging for the child DITA map.
To create an anchor in a DITA map, complete the following steps:
1. Open your DITA map file.
2. Insert an anchor tag in the beginning of your map.
3. Specify an ID for your anchor that will be used as the anchor reference in your component plug-ins.
Figure 3. anchorref tagging in a child DITA map
For example, Figure 4 illustrates where you specify the ID for your anchor.
The XHTML output will then look like the following example:
<topic label=”Business intelligence”>
<anchor id=”cv” />
Now your child or component DITA map can reference its position within the larger navigation or parent DITA map.
You should create an anchorref in your child DITA map when you are a component that will be placed in a larger navigation scheme, such as the DB2 Cube Views information in the DB2 UDB Information Center.
To create an anchorref in a child DITA map, complete the following steps:
1. Modify the attributes on your map tag.
2. Enter the relative path of the parent DITA map with your specific ID in the anchorref field. For example, …/com.ibm.db2.udb.doc/designing.ditamap#cv.
Now, you have a reference to the anchor in the parent DITA map.
When to use navrefs
You should use navrefs when the child DITA map will be reused in many places and will not have control of those places or, in some cases, will not know where or how it will be reused. For example, the information producers of Product A decided to have their information consumers use navrefs so that they do not need to coordinate anchor IDs with six different information consumers. The child DITA map does not need any significant tagging and would look like Figure 5.
Figure 4. Specifying an ID for an anchor
Figure 5. The child DITA map in a navref situation
The information consumers need to create a navref to the child DITA map in the parent DITA map where they would like to integrate the smaller component. For example, the Designing DITA map in Figure 6 on page 115 includes a navref directly to the location of the child DITA map.
Using a navref allows information consumers to pull in the smaller component where they need it, without additional coordination of specific, unique IDs.
To create a navref, complete the following steps:
1. Open your DITA map file.
2. Insert a navref tag in the beginning of your map.
3. Modify the attributes of the navref tag and enter the relative path of the child DITA map in the mapref field. For example, enter ../com.ibm.db2.udb.cv/cv_installing.ditamap.
Figure 6. A navref to a child DITA map that is located in the parent DITA map
Now, the child DITA map will be pulled into the location where you have put the navref in your file.
Anchors and navrefs at a glance
Both anchors and navrefs are used for runtime integration of navigation. The difference lies in whether the parent or child DITA map does the referencing. With anchors, the child DITA map references the location of the parent DITA map. With navrefs, the parent DITA map references the location of the child DITA map.
Use anchors in the following situations:
- The names of component DITA maps are volatile or cannot be determined by the consumer who creates 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 in the following situations:
- The names of DITA maps are known or can be determined by the consumer who creates the parent navigation.
- The child information components are being reused in multiple places (where synchronizing anchor IDs would be very complex).
- The child DITA map structure is final when the parent navigation ships to translation.
Component-based information architectures show promise for making information easier to reassemble as product, solution, and customer needs change. DITA provides excellent support through anchors and navrefs for integrating information components into information solutions. With planning and communication, both component providers and consumers can benefit.
Component-based information strategies are evolving. Delivery mechanisms, such as Eclipse, are continually improving their functionality with additions such as runtime filtering of content. This functionality could shape the way we use DITA in all of our information-development projects, including our componentization projects.
About the Authors
Carolyn Henry is an Information Developer in the Information Management division of the IBM Software Group. She is responsible for delivering Linux, UNIX, Windows, and z/OS product information for DB2 and IMS Tools. She has been authoring in DITA since December 2003. She holds a Masters in Technical and Professional Writing from Northeastern University and a Bachelor of Arts in English from Connecticut College. Carolyn leads a DITA Advocates group internally within IBM as well as the Silicon Valley DITA Advocates Special Interest Group (DITA SIG).
Information Strategist and Architect
Jennifer is an information strategist and architect in the Software Group at IBM. She is a member of the corporate information architecture council and has spent the last two years leading the creation of a unified information component model, implemented in DITA, for an extended product family. Her component work is based on over 15 years in information development, combined with experience as a software development manager.