Complex Maps for Componentized Products
You probably know by now that maps are DITA’s structure for organizing independent, reusable topics. You probably know that a DITA best practice is to define linking in the map rather than in the topics. You probably have some notion that your DITA maps should reflect the way users actually install and use your product. And you may know that the DITA Open Toolkit supports building multiple output types from a single DITA map.
Beyond that, though, do you have an architecture for your maps that accommodates all of your business requirements? Marketing and engineering often impose requirements that challenge you to look beyond the basic structural and reuse opportunities that DITA offers. Component-based products are a case in point.
Now You See It … Now You Don’t
Increasingly, new product offerings are built from a mix of components. Some offer new functionality; some are pieces of other standalone products. At Sybase, for example, Product A consists of a half-dozen separately installable components. While some basic functionality is common to all, most is not. User installation choices and licensing determine which product components—and which information components—are visible. Maintenance releases update some components but not all.
Our documentation CDs and website provide the complete collection. But when content is delivered as integrated help in the product, users only see documentation for the component they are using. Delivery and installation architecture must accommodate users with any mix of components.
Meanwhile, Product B presents different challenges. Here we need to deliver both Eclipse and Microsoft integrated help for two different user interfaces, with a mix of shared and UI-dependent content. In this case, users see a single, unified product rather than individual underlying components.
Divide and Conquer
Our solution to this dilemma: separate maps into multiple layers, as shown in Figure 1. One or more outer layers define output deliverable specifics but contain no topics. We dubbed these outer layers output maps. Examples of deliverable specifics include plug-in naming, PDF title page and header/footer information, and context-sensitive help enablement.
Figure 1: Layered map architecture
Nested in the output maps are content maps. Content maps reference topics and define linking. In Scenario A, where most components must exist independently, each component has its own content map; smaller maps may be nested inside the component content map. In Scenario B, where components are seamlessly integrated, the driving factor is the differing UI frameworks which require somewhat different content. Each UI framework has a content map, but it nests reusable maps in areas where information is common to each framework. For example, the overview content is framework-neutral, allowing reuse of these topics in a map nested in each framework content map.
In both cases, isolating content from output requirements makes our maps more reusable because the same content can be reused to produce a variety of output types.
Our output deliverables vary by product:
- All products deliver complete content to the web and CDs in an Eclipse Infocenter.
- All products deliver installation guides and release bulletins as PDFs.
- Some products deliver integrated Eclipse help in an Eclipse product UI, with or without context sensitivity. Eclipse help is delivered as plug-ins, just like other aspects of the user interface.
- Some products deliver integrated Microsoft help in a Visual Studio UI.
- Some products deliver Eclipse help wrapped in a Web UI.
- Some products deliver PDFs for all content.
- And some products deliver all of these.
The DITA Open Toolkit supports all of our output types. We have supplemented it with additional build tools and CSS modifications for each output format.
Component Content Maps
Our information components correspond roughly to product components. Within each component, a landing page, overview, and a set of task groupings move the user through a workflow that is as consistent as possible with other components (see Table 1).
Table 1: Product and Component Page Types
Component landing pages
Each component has its own landing page. This topic is the first in the component’s Contents list, and is one of the first pages returned from a search on the component name. The landing page drives users into four types of content: conceptual learning, high-level tasks, reference topics, and web or multimedia resources (see Figure 2, which shows DITA source above, and output below the DITA source). We positioned content types according to usability research: users notice content in the upper left first, then the upper right and lower left, while content in the lower right is least likely to be noticed.
Figure 2: Component landing page
Component Task Groupings
Task groupings provide a consistent architecture for tasks (see Figure 3). In some cases, the task groupings are DITA sequences; in other cases they are related tasks, defined in the relationship table. For example, in Scenario A, each product component offers software developers a set of tools for the complete development life cycle. We mimicked that life cycle structure in our content. Each information component is organized by stage of use: Basics, Plan, Set Up, Develop, Package, Deploy, Test, and Troubleshoot.
Figure 3: Component task groupings in the DITA map
Common tasks that apply to all components are defined in the content map for the Getting Started component, which is always installed. Other component maps have component-specific tasks. These information components are only installed when the corresponding product component is licensed.
This organization benefits us because not only is our content reusable but our architecture is as well. But more importantly, it aids our users. The task-based workflow guides users through complex tasks in the product. The consistent architecture helps users with multiple components find information without having to think too much: the pattern is familiar.
Our installation requirements influence our linking strategy. To prevent broken links, we can only link between topics that we know will be present. Thus, for products with license-based installation, we allow links only
- within a component
- from any component to other components that are always installed
Within those constraints, we apply a mix of DITA linking strategies:
- implicit linking between parent and child topics for most task groupings
- family collections in the topic hierarchy to add links among sibling topics
- relationship tables for additional linking within a component or for linking between component maps (but only to always-installed components)
Linking attributes satisfy other deliverable or content requirements:
- For links to web content and to PDFs not sourced in DITA, we set scope = “external”.
- For links between component maps—which in our case means between Eclipse plug-ins, we set scope = “peer”.
- For sequences defined in the relationship table, to avoid excess links, we disable linking in the topic hierarchy by setting linking = “none” or linking = “sourceonly”.
- For topics referenced in more than one sequence, we set the copy-to attribute on instances after the first so that we can define separate linking for each instance.
Installation and reusability also affect our context-sensitive help implementation. We add context IDs to metadata in the topics. The same topic can be used in more than one map, or more than once in the same map, but the code reference to the context ID needs the exact location of the topic.
Our solution is to take advantage of parts of the interface that are used across multiple components. This “always present” piece of the UI framework becomes the home for some context-sensitive help. While implementation details are beyond the scope of this article, essentially our method is to wrap context IDs in metadata on each topicref in the map that references a context-sensitive help topic.
Component Output Maps
An output map wraps the topmost content map for each component. We use various XML anchoring techniques to point from the top-level output maps that wrap the final deliverables and the component-level output maps that wrap the content maps.
In each component output map for integrated help in the product, we use an anchorref attribute on the map element followed by a topicref to the component content map. The anchorref supports license-based installation: the information is present when the component is licensed, but no error occurs when it is absent. IDs associate each output map with other maps it references. Figure 4 shows the anchorref attribute of a component output map, followed by a topicref to the corresponding content map.
Figure 4: Component output map—Eclipse product plug-in
By contrast, all components are always present in our Eclipse Infocenter, so an anchorref is not required, but (at least in this version of Eclipse) the ID format differs. The output map allows the plug-in naming convention to change so that multiple versions of documentation can be posted. For example, see the code in Figure 5.
Figure 5: Component output map—Eclipse Infocenter plug-in
Top-Level Output Maps
Top-level output maps assemble the finished content.
For the product UI, anchors allow components to appear only when installed, with no errors for missing content. Each anchor has an ID that associates it with a parallel anchorref in the component output map. Figure 6 shows the component anchors in the top-level output map and how those components appear in help in the product.
Figure 6: Top-level output map—Eclipse product plug-in
Infocenter (Web and CD)
For the web and CD, we don’t need anchors because all components are present, although the web includes some content that is not on the documentation CD. The top-level output map uses navrefs to pull in the landing page, output maps for release bulletins and installation guides (omitted in the example in Figure 7), new features guide, and the components. The last line in Figure 7 references another map that pulls in the output maps for all of the components so that they have a common heading in the Contents frame. Figure 8 the referenced map with navrefs to component output maps.
Figure 7: Top-level output excerpt—Eclipse Infocenter plug-in
Figure 8: Mid-level output map—Eclipse Infocenter plug-in
Choosing a Strategy
The anchor/anchorref strategy makes sense when components to be installed are chosen by users or automatically based on licensing options. For Eclipse deliverables, the build process produces multiple plug-ins that “assemble” in Eclipse to produce the TOC hierarchy. (You can use this strategy with other output formats, but you need to create a mechanism to process it correctly.) If a component is not installed, the anchor hierarchy is not broken. The component just doesn’t appear. All other components that are installed do appear. The maps that create the topic hierarchy and linking are independent of the output map that produces the output plug-in, and output for each of the content maps is produced independently.
On the other hand, if you do not have to contend with variable installation scenarios, you can simplify by using a nested content map strategy. You build a primary content map that nests all sub-maps. Output consists of a single deliverable unit: one plug-in, one PDF, one CHM file, and so on.
We originally adopted the output map strategy to accommodate technical differences between Eclipse versions for our Infocenter and our integrated product help. Over time, these differences have been eliminated and our implementation continues to evolve, but we’ve reconfirmed the value of output maps. Our PDFs and plug-ins have slightly different content that can be accommodated in the output map. Or, we may deliver complete content with a single output map for PDF but with separate output maps for each component plug-in.
Output maps also support our content management workflow. Content maps can move to their finished or “published” state, while final production tasks continue. Localization can proceed while production staff define the final web and CD plug-ins.
The output map strategy also aids staff development. Most of our writers are new to DITA. As they acquire topic-oriented authoring skills, they can move into the role of information architect gradually, developing their mapping skills first with the content. When they grow more confident with DITA—and as we solidify our strategies—more information architects can take on the more technical aspects of the output maps.
About the Author
Judy Kessler, Senior Staff Technical Writer at Sybase, Inc., has more than 30 years of experience in software documentation, as a writer, editor, and manager in the US and abroad. Currently, she serves as Transition Lead for Sybase’s move to DITA, responsible for developing guidelines and training for information architects, authors, and managers, leading pubs advisory councils, and advocating for DITA. She has presented at the Boston DITA User’s Group, Boston STC, CIDM
Showcase, and Content Management Strategies 2007 and 2008