Introduction to -Raghunath Soman (with valuable inputs from Taher Oliya)
What is DITA? DITA stands for Darwin Information Type Architecture XML-based, open-source documentation framework Originally created by IBM, currently managed by OASIS committee Latest specification version is 1.2
Why DITA? Enforces structured authoring Facilitates content re-use Supports single-sourcing Reduces translation costs Allows extension in form of specializations Effective for collaborative documentation projects Enables conditional processing based on target audience Generates output in all major formats: PDF, CHM, WebHelp, RTF, JavaHelp
DITA Tools Any XML editor such as Oxygen XML Editor in combination with DITA OpenToolkit Arbortext Editor Adobe FrameMaker 8 XMetal Author Xopus Online Editor
DITA Concepts Schema: base document that outlines the structure of XML Topics: generic document type Concepts: subjective information such as definitions, explanation, guidelines References: factual details, such as API description, command syntax Tasks: describes how to perform a specific procedure DITA Maps: logical organization of concepts, tasks and references Bookmaps: special kind of DITA map that defines the major structures for producing documentation as a book. Relationship Tables DITA elements and their attributes As of now, there are approximately 300 elements (tags) in DITA. Each element has a number of attributes specific to that element.
DITA Specializations Specialization feature of DITA allows extension of the core framework by adding industry-specific topic types, elements and attributes. Specialization is broadly categorized into two types: Topic specialization: creating new topic types Domain specialization: creating new elements and attributes Examples of topic specialization are: Message specialization Bookmap specialization Examples of domain specialization are: Training specialization Semiconductor industry specialization
Rules & Benefits of Specialization Basic Rules: The new information type and element must map to an existing one. The new information type must be more restrictive than the existing one in the content that they allow. For each new information type or topic specialization, a new DTD or a schema must be created. Major Benefits: Avoid re-inventing the wheel by re-using the base vocabulary Enables customized output with more specific search, filtering, and reuse Maintain consistency across multi-author teams Enforces explicit support of product architectural requirements
DITA Best Practices NOTE: These guidelines are only suggestions for best approach, and can/should be modified as per project-specific style guides. Analyze the content and break it into concepts, tasks and references. Avoid spaces in file names and folder names. Maintain a consistent naming convention across all file names. Nesting of multiple topics within a single file is discouraged. All root nodes should contain both a <title> and a <shortdesc> node immediately after it. Short description should be about 50 words long. Use complete sentences, and not sentence fragments. Do not merely re-state the topic title in different words. Use appropriate elements and attributes that best suit the content semantic. For example, use <ul>, <ol> and <dl> to enumerate bullets, numbers or definitions respectively.
DITA Resources DITA Wiki Knowledge Base DITA Specification v1.2 DITA News DITA World DITA Open Toolkit User Guide