Level 2: Scalable Reuse
Topic-oriented authoring creates reusable content organized around an audience's primary unit of use, the safest and most scalable reuse strategy for most modular content. The same topics can be reused, reassembled, and reorganized for different media and for different variations on a subject, such as documentation for product variants, by using DITA maps to encode higher-level structure, such as chapters or even Web pages, outside the topics that make up a deliverable.
A small technical publications team for a mobile phone vendor can organize the same content differently to optimize the user experience for a book versus a Web site. They can use the bookmap specialization to provide book-specific items, such as a cover page, notices page, and appendices, and another DITA map for the HTML output that does not require these items. They can also generate embedded online help from the same content for display directly on the phone.
The following figure shows the same topics appearing in multiple maps.
The major activities at this level are to break the content down into topics that are stored as individual files, and then to use DITA maps to collect and organize the content for output as specific deliverables. This effort requires that you create an information architecture that includes the following information:
- Lowest level of reuse, which may be at the phrase, element, topic, or map level.
- Strategy for content reuse, which identifies the mechanisms for reuse at each level.
- Metadata, which can be used for both build-time and run-time filtering if it is standardized and properly managed.
- User access paths, which specify how users access content and then navigate through deliverables using links between topics.
The ability to reuse content in a scalable manner depends upon knowing what you have, how it fits together, and what you need to do with it.
At this second level of adoption, you realize the value of flexible reuse by using DITA maps to assemble each deliverable. Because each map is specific to a deliverable, you can optimize the content to include the organization of the content and the links between the topics for each deliverable type.
DITA maps provide a way to abstract the relationships between topics that result in links from the topics and to specify the relationships within the map. This ability is crucial for reuse. You cannot reuse a topic in multiple components if it has a hard-coded link to another topic that might not be included in every component. When you specify component-specific relationships in the maps rather than including links in topics, you are free to use the topic in any component where the content applies without fear of broken links. In the following figure, Map 1 and Map 2 reference specific topics in a repository to generate multiple deliverable outputs.
Another way that DITA maps help you reuse information is by grouping sets of topics into units that can be further organized into components and easily included in multiple outputs. Consider the mobile phone technical publication team tasked with creating documentation for various phone models, each with different combinations of features. If the corresponding content for each feature set is organized by DITA maps, the technical team can quickly generate the appropriate documentation for each phone by assembling the feature set maps using a phone-specific map. In this way, the organization can tailor its documentation to specific end-user groups and thus increase customer satisfaction across those groups.
In addition to organizing topics into maps and applying conditional processing at the element, topic, and map levels, DITA provides a mechanism to reference content from one topic to another. With the conref attribute, you can reference content with a unique ID into another topic. The benefit is that you can maintain "a single source of the truth" in a topic and display that content in multiple places. Additionally, content updates performed at this single source will be automatically refl ected throughout all information outputs the next time you generate the topic. This mechanism is particularly useful for managing common content, such as legally approved notes or acronym lists, and for maintaining variable content, such as product names that require global updates across the content set.
In the case of the mobile phone technical publications team, instead of hard-coding a phone model name into the content, they can create a reference to the model name and conditionally process the reference to automatically include the appropriate name for each phone model.
However, you must have a strategy for tracking and communicating when information is referenced, updated, and generated. Without a strategy to handle this communication, there is a great risk of negatively impacting content accuracy and quality by inadvertently changing content.
Although you can reuse content with DITA in many ways while storing the content on a file system or in a source control system, you can only reuse content that you can find. This means that you must provide a way, through process or technology, for content authors to find and reuse information. Like a source control system, a content management system (CMS) maintains content integrity and supports content versioning; however, it also optimizes content retrieval through managed metadata and provides workfl ow management. In addition, a CMS can quickly identify where content is reused and help you avoid unintentional propagation of changes throughout the content set.
When you organize topics into deliverables by using maps, you can easily control the content for deliverables and generate custom output without impacting the content in the topics. In addition, you can reduce redundant authoring by reusing content at the element, topic, or map level.
DITA Features Used
This adoption level uses the following DITA features:
You create DITA maps to generate various deliverables. The DITA map serves three purposes: Manifest for the deliverable: all topics that contain content to appear in the deliverable must be listed in the map.
- Hierarchy for the deliverable: the TOC or hierarchy for the deliverable is determined by the nesting of the topics in the map.
- Defined relationships between topics: the non-hierarchical links between topics can be specified in the map, which allows the topics to be used for different deliverables.
DITA provides a reuse mechanism through the conref attribute, which allows you to reuse elements with a unique ID in various locations either within the same topic or another topic, as long as the source and target are the same element type. One consideration is that many content management systems only support references to entire files, so the content source must be saved as a separate file.