OASIS DITA Adoption TC

Join TC     TC Page     Send a comment to this TC

Educating the global marketplace on the value of DITA for document creation and management

JoAnn Hackos, joann.hackos@comtech-serv.com, Chair
Stanley Doherty, stan@modularwriting.com, Secretary
Robert Thomas, bob.thomas@tagsmiths.com, Secretary

Table of Contents


Announcements

DITA version 1.3 was approved as an OASIS Standard. Review details about the new version and download links. See the press release with executive endorsements from Adobe, Cisco, Comtech, IBM, ISIS Papyrus, IXIASOFT, Oracle, PTC, and SDL.

Overview

All Subcommittee work will be submitted to the DITA Adoption Committee for approval. For more information, see the DITA Adoption Committee Charter. Related information can also be found in the DITA TC Charter and FAQ


DITA Resources

http://dita.xml.org/
DITA XML Focus Area.
http://tech.groups.yahoo.com/group/dita-users/
DITA-users group, listserv, and support site with searchable archive.

Subcommittees


Technical Work Produced by the Committee

Wiki for OASIS DITA Adoption TC member collaboration


Expository Work Produced by the Committee

DITA 1.3 Webinar Learn about the new functions added in the DITA 1.3 specification. Listen to the webinar recording and download a PDF of the slides.

DITA 1.3 Feature Article: User Assistance Enhancements in DITA 1.3 DITA 1.3 provides enhanced support for context-sensitive help and other types of user assistance (UA). This article describes the DITA 1.3 features for user assistance.

DITA 1.3 Feature Article: Don't (XML) Mention It: Tagging XML Constructs in DITA 1.3 This article provides guidelines for using the DITA 1.3 XML Mention Domain. The XML Mention domain contains elements such as xmlelement and xmlatt.

DITA 1.3 Feature Article: Writing effective short descriptions This article discusses the benefits of using short descriptions and presents best practices for creating them.

DITA 1.3 Feature Article: About the DITA 1.3 release management domain The new release management domain in DITA 1.3 should prove to be a welcome addition for technical documentation departments seeking a solution for the problem of producing accurate release note content. As content is intended to be added at the topic and map level as it is being written, technical writers no longer have to rely on memory alone to document the major changes of a release. The date and time information embedded in the release management content allows for scripts to programmatically select only those comments that are pertinent to a given release, while still keeping information about all successive significant changes over the development of a product. Additional, optional information relating to bug tracking systems, the change requesters, and related information allows for tie-ins to external systems, and for authors to easily determine the source of significant changes. In short, the release management domain provides a convenient process for automatically and reliably handling release-specific information.

DITA 1.3 Feature Article: Understanding Scoped Keys in DITA 1.3 DITA 1.3 introduces scoped keys, which represent an extension of keys as introduced in DITA 1.2. Scoped keys enable you to define multiple values for a single key within a root map, specifying that each value should apply only within a specific part of the root map such as a sub-map, topichead, topicgroup, or even a single topicref.

DITA 1.3 Feature Article: About the DITA 1.3 release management domain The new release management domain in DITA 1.3 should prove to be a welcome addition for technical documentation departments seeking a solution for the problem of producing accurate release note content. As content is intended to be added at the topic and map level as it is being written, technical writers no longer have to rely on memory alone to document the major changes of a release. The date and time information embedded in the release management content allows for scripts to programmatically select only those comments that are pertinent to a given release, while still keeping information about all successive significant changes over the development of a product. Additional, optional information relating to bug tracking systems, the change requesters, and related information allows for tie-ins to external systems, and for authors to easily determine the source of significant changes. In short, the release management domain provides a convenient process for automatically and reliably handling release-specific information.

DITA 1.3 Feature Article: Making the Most of the New Math Domains in DITA 1.3 This paper provides an explanation of the elements of the equation domain, gives an introduction to the MathML domain, covers benefits and drawbacks of MathML in DITA, and finally gives an overview of tools to aid you in adding MathML support to your DITA documents today.

DITA 1.3 Feature Article: Using DITA 1.3 Troubleshooting Information developers recognize that a high percentage of users seek information only when they experience a problem. First, they become aware of the problem, often because they receive an error message or an outcome they expected fails to occur (for example, “the machine should turn on but does not”). Second, they articulate or define the problem, putting it into words (for example, “I cannot get this font to change size”). At this point, they begin to search for content that might help them solve the problem. At this stage, the users might be reading the manual, searching for relevant information. However, most manuals “pose formidable obstacles to finding problem-solving information.” The Troubleshooting additions to DITA 1.3 are designed to overcome the obstacles and make it easier for users to identify problem-solving information. A recording of the webinar on this topic is available here on YouTube.

DITA 1.2 Feature Article: Roles and Responsibilities of a DITA Implementation DITA (Darwin Information Typing Architecture) adoption is more than a simple change of tools. Implementing DITA can increase the quality of your documentation, streamline your authoring, reviewing, publishing, and translation processes, and introduce new outputs and user experience of published content. Adopting a DITA writing environment requires a number of key roles. The individuals in these roles develop an adoption plan, get approval and funding for the adoption, and implement a series of strategies, processes, and tools that meet the requirements of your organization. An effective DITA adoption directly and positively impacts the end-user experience with your products and with your company. An effective DITA writing environment makes authoring, reviewing, publishing, and translating content faster and easier.
A recording of the webinar on this topic is available here on YouTube.
A PDF copy of the slides is also available. Roles and Responsibilities Webinar Slides
Japanese version of the DITA Roles and Responsibilities Feature Article. Japanese DITA Roles and Responsibilities Feature Article

DITA 1.2 Feature Article: Using XLIFF to Translate DITA Projects DITA promises cost reductions in translation thanks to content reuse. Content reuse can lead to translation cost reduction when proper planning is done. DITA topics are written once, updated once, and used in multiple deliverables. With careful planning, costs can indeed be lowered. However, cost reduction depends on the nature of the project; it is not possible to predict the level of cost reductions in advance. XLIFF (XML Localization Interchange File Format) is an open standard published by OASIS (like DITA) that you can use in your project workflow to manage the content that needs to be translated.

DITA to XLIFF and Back - Reducing the Costs and Risks of Translating XML Content presents a business perspective on translating topic-oriented, XML-based content. The webinar includes business cases developed by expert panelists

DITA to XLIFF and Back - Understanding the Technical Solution describes in technical terms how DITA can be used with XLIFF, which provides an easy-to-use mechanism for packaging DITA files for translation and localization providers. A real world 'end-to-end' enterprise implementation is demonstrated.

DITA 1.2 Feature Article: Tools and DITA Awareness The DITA Specification explicitly or implicitly prescribes behaviors for "processors" or "tools", and sometimes refers to them as being "DITA-aware" or "specialization-aware." The term "processor" and "tool" are used interchangeably in the specification. This document describes the concepts of DITA-awareness and specialization-awareness, and explains how these concepts apply to processors.

DITA 1.2 Feature Article: Acronym Best Practices This article, developed by the OASIS DITA Translation Subcommittee, provides best practices for handling acronyms and abbreviations in text to be translated. It explains potential problems using the conref mechanism for acronyms and abbreviations and how to resolve them.

DITA 1.2 Feature Article: Task Model This article explains the new task model introduced in DITA 1.2 and provides recommendations on using it in conjunction with the original task model. Both models are available in DITA 1.2.

DITA 1.2 Feature Article: Domain and topic integration In DITA 1.2 the integration of domains and topics has been unified to improve design flexibility and to simplify the DITA specialization constructs. The restrictions on module inheritance have been relaxed enabling vocabulary elements to be shared between different types of modules.

DITA 1.2 Feature Description: Conref Push This article explores the new conref push feature introduced in DITA 1.2, which enables users to insert or replace content in DITA topics and maps.

DITA 1.2 Keyref: Feature Description Explores the capabilities of the new keyref feature introduced in DITA 1.2.

DITA 1.2 Glossary and Terminology Specialization Feature Description Detailed description of the DITA 1.2 glossary specialization and recommendations for its best use.

DITA 1.2 Referencing a Range of Elements: Feature Description Detailed description of best practices for referencing a range of elements.

DITA 1.2 Feature Description: Improved glossary and terminology handling This whitepaper describes the improved glossary and terminology handling features in DITA 1.2. A new glossary entry element provides a flexible semantic structure to store terminology information, and the new indirect linking functionality allows terms occurring it the content to be linked through a key reference, or transcluded using a new abbreviated-form element. Keys used for key referencing are defined in a new glossref specialisation of topicref in the map.

Best Practices for Using the DITA Conref Attribute in DITA for Translation Great care should be taken regarding the use of the conref attribute in DITA topics that will be translated. The conref attribute may appear to be a very efficient artifice to allow for the simple substitution of product names and other variables, allowing for the runtime resolution of given parameters. However, runtime resolution can cause grammatical problems with highly inflected and gender sensitive languages such as most Slavonic and Germanic languages, where nouns can change (both root and ending changes are possible) depending on case/context.

Best Practice for Indexing DITA Topics for Translation Inserting an inline element such as anywhere into a block element may present problems for translation. In addition, translation memory (TM), which stores segments that have been previously translated, may not match segments that are divided by index tags, especially if the index tag has been added or moved since the previous translation. The practice shows how to create translatable indexes.

Best Practice for Leveraging Legacy Translation Memory when Migrating to DITA Many organizations have previously translated content that was authored in non-XML tools, such as desktop publishing applications. When migrating their legacy content into the new DITA authoring environment, what does an organization do about their legacy translation memory? This legacy translation memory (TM) has been created with large financial investments that can't easily be discarded simply because a new authoring architecture is being adopted. This paper describes best practices that will help organizations use their legacy TM for future translation projects that are authored in DITA XML. These practices will allow them to minimize the expense of ongoing translations of XML-based content.



Providing Feedback: OASIS welcomes feedback on its technical activities from potential users, developers, and others to better assure the interoperability and quality of OASIS work.