Introduction to DITA: Advanced DITA Techniques

As your content needs grow, mastering advanced DITA techniques becomes essential. In this blog, we’ll explore some advanced strategies for reusing content, managing variables, working with conditional text, and customizing your DITA implementation through specialization.

Let’s get started.

Note: Missed the first two blogs in this series? Read them here:

- Part 1: An Overview

- Part 2: Best Practices and CCMS Integration

1. Mastering Content Reuse with Conrefs and Keyrefs

One of DITA's most powerful features is the ability to reuse content across different topics or documents. This is where Conrefs (Content References) and Keyrefs (Key References) come into play. These mechanisms allow you to efficiently manage and update content without having to replicate it in multiple locations.

Understanding Conrefs (Content References)

A conref allows you to insert content from one topic into another by referencing it. For example, if you have a standard warning that applies to multiple procedures, you don’t have to rewrite that warning in each procedure. Instead, you create it once and use a conref to reference it wherever needed.

Imagine you are documenting safety procedures for different machines. Each machine has the same safety warning about electrical hazards. Instead of copying and pasting that warning into every procedure, you can create a single topic with the warning and reference it using conrefs.

Best Practices:

• Use conrefs for content that is likely to change. This way, updating the original reference automatically updates all the instances where it is used.

• Organize your reusable content in a dedicated folder or section to make it easy to find and manage.

Leveraging Keyrefs for Dynamic Content

While conrefs are excellent for static content reuse, keyrefs allow for more dynamic referencing. Keyrefs let you pull in content based on a key, which can change depending on the context in which the document is used. This makes keyrefs ideal for managing content that varies across outputs without modifying the source topics.

You could use a keyref to reference a product name that changes based on the document version (e.g., a software update). By defining the product name in a keymap, you can ensure that the correct product name is pulled into all the topics, without manually updating each reference.

Best Practices:

• Use keyrefs for content that changes frequently, such as product names, version numbers, or URLs.

• Maintain a well-structured keymap to make managing and updating keys easier.

2. Efficient Management of Variables and Conditional Text

Managing content across different products, versions, or user roles often requires the use of variables and conditional text. These techniques help customize your documentation for different audiences or outputs without creating separate documents for each scenario.

Using Variables for Consistent Output

Variables in DITA are placeholders that allow you to manage content that changes across different outputs, such as product names, version numbers, or company-specific terminology. When a variable is updated, all occurrences of that variable in your documentation are updated automatically.

Let’s say your company releases new versions of its software every few months. By defining the version number as a variable, you can ensure that it’s updated in all your topics when a new release comes out, saving time and reducing errors.

Best Practices:

• Define variables for content that frequently changes, such as product names, customer names, and release numbers.

• Store your variables in a dedicated section or file to make updates more manageable.

Conditional Text for Customized Documentation

Conditional text allows you to include or exclude content based on specific conditions, such as audience type, product version, or output format. This is particularly useful when producing customized documentation for different user groups or delivering different versions of the same document (e.g., for print vs. web).

You might have a procedure that differs slightly for administrators and general users. By applying conditional attributes, you can produce customized versions of the documentation for each role without duplicating the content.

Best Practices:

• Use profiling attributes to manage content variations based on audience, platform, or language.

• Keep your conditional text rules simple to avoid creating overly complex content management challenges.

3. Advanced Map Management Techniques

As your DITA documentation set grows, you’ll need more advanced techniques to organize and manage your content. This is where DITA maps and submaps come into play, allowing you to structure large documentation sets into manageable modules.

Organizing Content with DITA Maps

A DITA map is a file that organizes your topics into a structured hierarchy, making it easier to navigate and publish your content. Maps allow you to group related topics and manage them as a single document set.

Submaps are smaller maps that can be included in a master map. Breaking down large documents into submaps allows for easier updates and better content management.

Best Practices:

• Use submaps to modularize large documentation sets, especially when different teams are responsible for different sections.

• Organize your maps to reflect the logical structure of your content, making it easier for authors and reviewers to navigate.

Working with Relationship Tables

DITA maps also allow you to define relationships between topics using relationship tables. These relationships are useful for linking related content, such as topics that describe different aspects of the same product or process.

4. DITA Specialization for Custom Content Requirements

DITA’s standard structure is flexible, but some industries or organizations may have unique documentation requirements. Specialization allows you to create new elements based on existing DITA elements to meet specific needs.

What is DITA Specialization?

Specialization involves creating new content models by extending existing DITA elements. For example, a medical device company might need specialized elements for regulatory documentation. By specializing DITA, you can create custom elements while maintaining compatibility with standard DITA tools.

A company specializing in pharmaceuticals may need to document clinical trials. By specializing DITA, they can create specific elements for trial protocols, patient consent forms, and regulatory submissions.

Best Practices:

• Plan your specialization carefully to ensure it’s maintainable and doesn’t complicate your content model.

• Ensure that your specialized elements are compatible with the DITA Open Toolkit (DITA-OT) for seamless publishing.

DITA Tools and Resources

Let's wrap up our series on DITA with some tools to help author and manage DITA, and some resources to further your learning.

A List of Tools, Plugins, and Extensions for DITA

• Oxygen XML Editor: A comprehensive XML authoring tool with built-in support for DITA, including validation, transformation, and content management features.

• DITA Open Toolkit (DITA-OT): The standard publishing engine for DITA, used to transform XML content into various output formats.

• XMetaL Author: A user-friendly DITA editor that offers WYSIWYG editing, content validation, and integration with content management systems.

• Arbortext Editor: A high-end XML editor with advanced capabilities for structured content authoring, particularly suited for complex documentation environments.

• DITA Exchange: A plugin that allows for the integration of DITA content with Microsoft SharePoint.

• Content Fusion: A collaboration tool for DITA that facilitates real-time content review and editing.

Resources for Further Learning: Books, Courses, and Online Communities

Books:

• “DITA for Practitioners: The Architecture and Technology of DITA” by Eliot Kimber: A comprehensive guide to DITA, covering its architecture, technology, and best practices.

• “The DITA Style Guide” by Tony Self: A practical guide to writing effective DITA content, with tips on style, structure, and language.

Courses:

• DITA Training from Scriptorium: Offers a range of courses on DITA, from introductory sessions to advanced workshops.

• OASIS DITA Learning Center: Provides resources and tutorials for DITA authors, including webinars and online courses.

Online Communities:

• DITA Users Group (LinkedIn): A community of DITA professionals who share knowledge, ask questions, and discuss best practices.

• Oxygen XML Forum: A forum for users of Oxygen XML Editor to discuss DITA authoring, troubleshooting, and customizations.

The Wrap: Optimizing Your DITA Workflow

Mastering advanced DITA techniques like conrefs, keyrefs, map management, and specialization can help streamline your content production workflow and ensure consistency across large documentation sets. By applying these best practices, you can make your content more modular, flexible, and adaptable to the evolving needs of your organization.

That's it for our series on DITA. We hope you found it helpful.