Introduction to DITA: Getting Started
DITA (Darwin Information Typing Architecture) is a structured content standard based on XML. It was originally developed by IBM in 2001 to address the needs of technical writers who required a more modular and reusable way to create documentation.
The architecture was later adopted as an OASIS (Organization for the Advancement of Structured Information Standards) standard, which has led to its widespread use in various industries, including software, healthcare, manufacturing, and finance.
DITA’s key strength lies in its topic-based authoring approach. Unlike traditional linear documents, DITA encourages the creation of modular pieces of content—known as topics—that can be independently authored, reviewed, and reused. This modularity allows content creators to manage complex documentation with greater efficiency, maintain consistency across different publications, and reduce redundancy.
Key Components of DITA
- Topics: Topics are the smallest unit of information in DITA. Each topic should cover a single subject, task, or concept. There are three main types of topics in DITA:
- Concepts: These topics explain ideas or provide background information. They are often used to describe the “what” or “why” of a subject.
- Tasks: Task topics provide step-by-step instructions on how to perform a specific action. They are the “how-to” guides within DITA.
- References: These topics contain factual data, such as technical specifications, tables, or lists. They are used for detailed information that users may need to refer to repeatedly.
- Maps: DITA maps are hierarchical structures that organize topics into a coherent document. A map defines the relationship between topics and their order of presentation in the final output. DITA maps are also used to manage content variations for different audiences or outputs by including or excluding specific topics.
- DITA Open Toolkit (DITA-OT): The DITA Open Toolkit is an open-source publishing engine that processes DITA content into multiple output formats, such as HTML, PDF, ePub, and others. The DITA-OT is highly customizable and allows for complex transformations, making it a crucial tool for organizations that need to publish content across various platforms and devices.
Getting Started with DITA
There are several steps involved in getting started writing DITA content. Here are the basic steps to help you get up and running.
Choose an XML Editor:
To write DITA content, you need an XML editor:
- Fonto: A web-based XML editor specifically designed for structured content, including DITA. It provides a user-friendly interface that simplifies DITA authoring for non-technical users.
- Oxygen XML Editor: A robust XML authoring tool that supports DITA and offers a wide range of features for writing, validating, and publishing DITA content.
- XMetaL: A user-friendly XML editor tailored for DITA authoring, offering WYSIWYG editing, integration with content management systems, and robust publishing options.
- Arbortext Editor: A high-end XML editor used for creating structured content, particularly in environments where complex document assembly is required.
Install the DITA Open Toolkit:
Download the latest version of the DITA-OT from the official website and install it on your system. Follow the installation instructions to ensure that the toolkit is configured correctly for your environment.
Set Up a Project:
Create a folder structure that organizes your DITA topics, maps, and other resources. A typical structure might include folders for concepts, tasks, references, maps, images, and stylesheets.
Use your XML editor to create a new DITA map. Add topics to the map in the desired order and use the map editor to manage the hierarchy and relationships between topics.
Author Content:
Begin writing your topics using the DITA standard elements. Use <title>, <shortdesc>, <body>, <section>, and other relevant elements to structure your content.
Include metadata in your topics, such as keywords, audience types, and product information, to improve content management and searchability within the CCMS.
Publish Content:
Use the DITA-OT to transform your DITA content into the required output formats. Customize the transformation scenarios if necessary to match your organization’s branding and style guidelines.
After publishing, review the output to ensure that it meets your quality standards. Check for formatting issues, broken links, and any discrepancies between the source content and the published document.
Examples of Basic DITA Projects
There are many different types of DITA projects you can create. The following are the most common ones you can expect to work on.
Product Documentation:
- User Guides: Develop user guides that include installation instructions, configuration steps, and troubleshooting information. Each topic within the guide should be reusable across different versions or products.
- API Documentation: Create API documentation with topics that describe endpoints, request/response structures, and code examples.
Training Materials:
- Lesson Plans: Author lesson plans with topics that explain key concepts, provide step-by-step instructions, and include quizzes or exercises.
- E-learning Modules: Develop e-learning content that can be easily repurposed across different courses or training programs.
Knowledge Base:
- Technical Articles: Write technical articles on various topics, such as system configurations, common issues, and best practices.
- FAQs: Compile a collection of frequently asked questions with detailed answers, organized by category for easy access.
4 Real-World Applications
To help you understand how DITA can help you with your documentation workflows, let’s look at a few examples. We’ll use different industries too, so you can see how DITA works for different types of companies.
Technology Companies
Technology companies can use DITA to produce user guides, API documentation, and knowledge base articles. By adopting DITA, these companies can achieve faster content updates and more consistent documentation across product lines.
Financial Services Providers
Financial services providers can implement DITA to manage regulatory compliance documentation. With DITA’s modular approach, they can quickly update content in response to changing regulations while maintaining accuracy and consistency.
Multinational Manufacturing Companies
Manufacturing companies manage a large volume of technical documentation for product lines, each with multiple variations. By transitioning to DITA and integrating it with a CCMS, they can streamline their documentation process, reduce redundancy, and improve the quality of their content.
Healthcare Organizations
Healthcare organizations need a robust documentation system to handle complex medical information and ensure compliance with industry regulations. Using DITA and a CCMS, they can maintain high standards of accuracy and compliance.
3 Frequently Asked Questions (FAQs)
You probably have lots of questions right now, but in our experience, there are three we hear a lot, so let’s address them now.
FAQ 1: What are the advantages of using DITA over traditional documentation methods?
Answer: DITA’s modular approach allows for greater content reuse, consistency, and efficiency. It also supports multiple output formats, making it ideal for organizations that need to publish content across various platforms and devices.
FAQ 2: How does DITA handle localization?
Answer: DITA supports localization through its conditional text and keyref mechanisms. You can create content variations for different languages or regions and manage them within a single source.
FAQ 3: What tools are available for DITA authoring?
Answer: Several XML editors support DITA, including Oxygen XML Editor, XMetaL, and Arbortext Editor. These tools offer features tailored to DITA authoring, such as content validation, transformation scenarios, and integration with CCMS.
Glossary of DITA Terms
Let’s close with some key terms. If you’re new to DITA, it will help to understand these terms at minimum:
- Topic: The smallest unit of content in DITA, representing a single subject, task, or concept.
- Map: A DITA file that organizes topics into a structured document or hierarchy.
- DITA Element: A building block in DITA, representing different types of content, such as paragraphs, lists, or tables. These elements are predefined but can be specialized.
- Metadata: Information that describes and categorizes DITA content, such as author, date, or keywords, helping with content organization and retrieval.
- Chunking: The process of breaking content into smaller, reusable pieces, allowing for better modularity and flexibility in DITA.
- Profiling: A method for filtering content based on attributes (like audience, product, or platform) to deliver customized outputs from a single source.
- DITA Domain: A set of related elements and attributes in DITA, used for specific content types (e.g., technical documentation, software help, etc.), allowing further customization of content types within the DITA framework.
- Conref: A content reference that allows you to reuse content across multiple topics.
- Keyref: A reference that uses keys to pull in content, providing flexibility in content reuse.
- Specialization: The process of extending DITA by creating new elements based on existing ones.
- Conditional Text: Content that is included or excluded based on specific conditions.
- DITA Open Toolkit (DITA-OT): A publishing engine that transforms DITA content into various output formats.
What’s Up Next
We’ve gone through an overview of what DITA is and how you get started with a DITA project. We also looked at some typical DITA projects, industry use cases, and closed with a few frequently asked questions and key terms. That should give you a foundational understanding of DITA and how to work with it. Up next, we’re going to go through some best practices and explain how you use a component content management system (CCMS) to manage your DITA projects.
