DITA 1.3: Why Three Editions? Version 1.0
Committee Note 01
17 November 2015

Specification URIs

Previous version

Not applicable.

Chair

Kristen James Eberlein (kris@eberleinconsulting.com), Eberlein Consulting LLC

Editors

Additional artifacts

This document is part of a work product that also includes:

Abstract

DITA 1.3 is distributed in three editions to better serve the needs of specific user communities. The specific user communities are those that are interested in:

  • Core DITA
  • Technical content
  • Learning, training, and instructional design

This committee note explains the rationale for the three editions; it also provides an overview of what each edition contains, the intended audience of each edition, and metrics about each edition.

Status

This document was last revised or approved by the OASIS Darwin Information Typing Architecture (DITA) TC on the above date. The level of approval is also listed above. Check the “Latest version” location noted above for possible later revisions of this document.

TC members should send comments on this document to the TC’s email list. Others should send comments to the TC’s public comment list, after subscribing to it by following the instructions at the “Send A Comment” button on the TC’s web page at https://www.oasis-open.org/committees/comments/index.php?wg_abbrev=dita.

Citation format

When referencing this note, the following citation format should be used:

[DITA-why-three-editions]
DITA 1.3: Why Three Editions? Version 1.0. Edited by Kristen James Eberlein, Nancy Harrison, John Hunt, and Amber Swope. 17 November 2015. Committee Note 01. http://docs.oasis-open.org/dita/dita-1.3-why-three-editions/v1.0/cn01/dita-1.3-why-three-editions-v1.0-cn01.html. Latest version: http://docs.oasis-open.org/dita/dita-1.3-why-three-editions/v1.0/dita-1.3-why-three-editions-v1.0.html.

Notices

Copyright © OASIS Open 2015. All Rights Reserved.

All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Table of Contents

1 Introduction

For DITA 1.3, the OASIS DITA Technical Committee decided to issue the specification in three editions: Base, technical content, and all-inclusive.

Block diagram that illustrates the components of the three editions of the DITA specification, and the subset relationships between the three editions. The base edition ('part 1') contains the base architecture, which includes map, topic, subject scheme, and DITAVAL. The technical content edition ('part 2') contains the base architecture plus the technical content specializations, which include concept, task, reference, book map, glossary, classification map, machine industry, and troubleshooting. The alll-inclusive Edition ('part 3') contains the base architecture, the technical content specializations, and the learning and training specializations.

This committee note explains the rationale for the three editions; it also provides an overview of what each edition contains, the intended audience of each edition, and metrics about each edition.

1.1 Terminology

This section provides information about terminology and how it is used in this committee note.

document type
A type of DITA topic or map that is designed for a specific purpose.
domain
A group of elements (or an attribute) that can be made available in a DITA topic or map type.
information typing
A methodology in which information is organized and classified according to its purpose. This methodology is central to the practice of structured authoring; It is based on extensive research and experience, including Robert Horn's Information Mapping and Hughes Aircraft's STOP (Sequential Thematic Organization of Proposals) technique.
specialization
The process of creating a new DITA element or attribute from an existing element or attribute. The new element or attribute inherits characteristics from the element or attribute from which it was specialized, which reduces design work and enables the reuse of existing transformations.
XML grammar files
The files that define the content model and attributes for a DITA document type.

2 Why are there three editions of DITA 1.3?

DITA 1.3 is distributed in three editions to better serve the needs of specific user communities.
The user communities are those that are interested in:
  • Core DITA
  • Technical content
  • Learning, training, and instructional design

The distribution of DITA 1.3 in three editions also reflects several interconnected factors, including new audiences for DITA, a new focus on topic and map as the core document types, and the growth of DITA over the decade that it has been an OASIS standard. The three-edition distribution also heralds changes to come in the future.

2.1 New audiences for DITA

DITA has spread well beyond its origins in technical communication.

DITA is now in use in the following fields, among others:

  • Entertainment
  • Health and wellness
  • Instructional design
  • Marketing
  • Medical information
  • Pharmaceuticals
  • Publishing

2.2 The core of DITA: Topic and map

The DITA Technical Committee wants to emphasize that topic and map are the base document types in the architecture.

Because DITA was originally developed within IBM as a solution for technical documentation, early information about DITA stressed the importance of the concept, task, and reference topics.

Many regarded the topic document type as nothing more than a specialization base for concept, task, and reference.

While this perspective might still be valid for technical content, times have changed. DITA now is used in many other contexts, and people developing content for these other contexts need new specializations. For example, nurses who develop evidence-based care sheets might need a topic specialization that has sections for evidence, impact on current practices, and bibliographic references.

The structure of the three editions makes it very clear that topic and map are the base document types, and that the other document types are specializations designed for specific user communities – currently technical content and learning and training.

2.3 Growth of DITA

Since its first release in 2005, each subsequent release of DITA has included new document and element types.

Metric DITA 1.0 DITA 1.1 DITA 1.2
Number of document types 6 9 23
Number of element types 193 299 535
Number of pages of PDF version of the specification 292 593 1,236

The growth was natural and organic, as DITA evolved to better meet the needs of its users. DITA 1.1 introduced DITAVAL (a standard mechanism for defining a conditional-processing profile) and the book map (a specialized map for producing book-oriented publications). DITA 1.2 introduced even more document and element types, including the learning and training specializations, new variants of the task topic, glossary specializations, and taxonomic specializations. Between DITA 1.0 and 1.2, the number of elements more than doubled.

This increase in the number of elements scared some users, despite the fact that most users never used (or even saw) the majority of the new elements. As a result, the DITA Technical Committee planned to release DITA 1.3 in three editions, each optimized for specific users. This improves the chances of users getting only the pieces of DITA that they need—no more, no less.

The following table provides basic metrics about the sizes of the three editions.

Metric Base edition Technical content edition All-inclusive edition
Number of document types 4 17 26
Number of element types 189 440 621
Number of pages of PDF version of the specification 455 867 1,199

The subsequent chapters in this committee note provide information about each edition – what it contains and the intended audience – that is designed to help readers determine which edition best fits their needs.

Finally, note that even though DITA 1.3 includes new document and element types, the number of pages in the PDF version of the specification has decreased slightly. This is due to improvements in the information design. In addition, the DITA 1.3 specification has been made more usable by the addition of more examples and code samples that illustrate DITA features and mechanisms.

2.4 Future of DITA

The three editions of DITA 1.3 set the stage for future developments: Lightweight DITA and DITA 2.0.

Lightweight DITA

In July 2014, the OASIS DITA Technical Committee formed the Lightweight DITA subcommittee, chaired by Michael Priestley of IBM.

The goal of the Lightweight DITA effort is to develop a specification for a lightweight architecture that will ease implementation by vendors and adoption by users. The architecture will provide:

  • Easy out-of-the box authoring for common topic types
  • Out-of-the-box mappings and specifications for authoring the common topic types in other formats, such as HTML5 and Markdown
  • Easy assembly of new specializations from existing section types
  • Easy creation of new specializations by generating them from a topic type designed for specialization creation

DITA 2.0

While work on DITA 2.0 is in the very early stages, there is general consensus among the DITA Technical Committee on the following points:

Architectural redesign
DITA 2.0 will provide an opportunity for the DITA Technical Committee to revisit and redesign aspects of the architecture that are less than optimal, such as chunking.
Backwards compatibility
DITA 2.0 will not be backwards compatible. Throughout the DITA 1.x releases, the DITA Technical Committee has gone to great pains to ensure that it did not add designs or features that might break existing implementations. For DITA 2.0, the DITA Technical Committee plans to relax this restriction, so that it can revisit some early design choices and remove deprecated elements. The DITA Technical Committee will minimize disruption and provide clear, documented migration paths to ease transition to DITA 2.0.
Modularity
The DITA Technical Committee plans to continue the practice of designing increasingly targeted releases and editions.

3 Base edition

The base edition is the smallest edition of the DITA 1.3 specification.

Block diagram that illustrates the components of the three editions of the DITA 1.3 specification, and the subset relationships between the three editions. The base edition ('part 1') contains the base architecture, which includes map, topic, subject scheme, and DITAVAL. The technical content edition ('part 2') contains the base architecture plus the technical content specializations, which include concept, task, reference, book map, glossary, classification map, machine industry, and troubleshooting. The all-inclusive edition ('part 3') contains the base architecture, the technical content specializations, and the learning and training specializations. Portions of this diagram that are specific to the base edition are highlighted and bold, while others are dimmed, to signify that this is the base edition of the DITA 1.3 specification.

3.1 What is in it?

The base edition contains the following document types:

Base topic
The document type that is the basic unit of authoring and reuse.
Base map
The document type that organizes topics and other resources into structured collections of information. It specifies hierarchy and the relationships between the resources.
Subject scheme
A specialized map that can be used to define controlled values and taxonomic subjects.
DITAVAL
A document type that can be used to define conditional-processing profiles.

3.2 Audience

The base edition is designed for application developers and people who need only the most fundamental pieces of the DITA framework.

Such users might include:

  • Authors who do not need detailed information typing
  • Developers building light-weight DITA-enabled applications
  • DITA practitioners developing specializations that use topic as the specialization base

Users who create technical content should consider the technical content edition. Users who create learning and training materials should consider the all-inclusive edition.

3.3 What can this edition be used for?

This edition can be used for out-of-the-box authoring; it also can be used to develop specializations for fields other than technical content or learning and training.

Examples of such specializations might include the following:

  • Recipe
  • Product data sheet
  • Media topic that contains a title, metadata, an image or video, and a caption
  • Information about when to call a doctor
  • A topic that is designed to hold cover-page information for a basic publication
  • Event listing for an online calendar

3.4 Size of the base edition

You can consider several metrics concerning the size of the base edition.

Number of document types 4
Number of element types 189
Number of pages of PDF version of the specification 455:
  • TOC and introduction: 20
  • Overview, features, and examples: 158
  • Element definitions: 197
  • Appendixes: 80

4 Technical content edition

The technical content edition is the medium-sized edition of the DITA 1.3 specification. It includes the base architecture and the specializations that are usually used for technical content.

Block diagram that illustrates the components of the three editions of the DITA specification, and the subset relationships between the three editions. The base edition ('part 1') contains the base architecture, which includes map, topic, subject scheme, and DITAVAL. The technical content edition ('part 2') contains the base architecture plus the technical content specializations, which include concept, task, reference, book map, glossary, classification map, machine industry, and troubleshooting. The all-inclusive edition ('part 3') contains the base architecture, the technical content specializations, and the learning and training specializations. Portions of this diagram that are specific to the technical content edition are highlighted and bold, while others are dimmed, to signify that this is the technical content edition of the specification.

4.1 What is in it?

The technical content edition contains the following document types, in addition to those from the base edition.

Topics

The technical content edition includes these technical-content topic types:

Composite
The composite topic (sometimes called ditabase) can contain other topic types. In the out-of-the-box OASIS distribution, it can contain topic, task, concept, reference, troubleshooting, glossentry, and glossgroup. These topics can be in any sequence.
Concept
A specialized topic that provides conceptual information. Conceptual information provides the background knowledge that enables readers to understand why they might need to perform a particular task or use a particular product. It might include extended definitions or explanations.
Glossary entry
A specialized topic that defines a term. It also can identify the part of speech and provide information about usage, acronyms, abbreviations, variant terms, synonyms, and associated symbols or graphics.
Glossary group
A specialized topic that can contain multiple glossary entry topics.
Machine industry task
A specialized topic that can be used to document tasks that involve machines or hardware. It can contain additional information about required personnel, safety conditions, support equipment, necessary supplies, and spare parts.
Reference
A specialized topic that provides facts that support a task, such as hardware specifications, required equipment, programming syntax, command-line interface parameters, or other information that might need to be accessed infrequently as a person performs a task.
Task and General task
The (strict) task is a specialized topic that provides step-by-step instruction about how to perform an action, plus brief information about when, where, why, and by whom the action is performed.
The general task has a looser content model than the task topic type, and it can be useful for migrating legacy content to DITA.
Topic
The document type that is the basic unit of authoring and reuse. In addition to the domains that are included in the base topic, this document type also includes domains that are useful for technical content.
Troubleshooting
A specialized topic that provides corrective action information such as troubleshooting and alarm clearing.

Maps

The technical content edition includes these technical-content map types:

Book map
A specialized map that can be used to produce book-oriented publications. Book maps enable authors to organize content into front matter, prefaces, chapters, parts, back matter, and more. In addition, they also include a set of metadata elements that can capture information about the book.
Classification map
A specialized map that can be used to associate subjects defined in a subject scheme map with topics referenced in a DITA map.
Map
The document type that organizes topics and other resources into structured collections of information. It specifies hierarchy and the relationships between the resources. In addition to the domains that are included in the base map, this document type also includes domains that are useful for technical content.

4.2 Audience

The technical content edition is designed for authors who document complex applications and devices, such as software, hardware, medical devices, machinery, and more.

Such users might include:

  • Technical communicators who use information typing and author task-oriented content
  • Business analysts who document procedures and the processes that they support
  • Anyone who needs to create a glossary
  • Authors who need to create book-oriented publications that include front matter and back matter, chapters and appendixes, or bibliographical metadata such as copyright dates or copyright holders
  • Organizations that need to keep detailed records of how, when, and by whom their documents have been modified in order to comply with government or industry regulations.

4.3 What can this edition be used for?

This edition can be used for out-of-the-box authoring; it also can be used by DITA practitioners to develop specializations for industries such as software, hardware, manufacturing, and publishing.

Examples of such content and specializations might include the following:

  • Printed hardware or software manuals
  • Online or mobile help systems for medical devices
  • Hover help for filling out fields in an online form
  • Repair or troubleshooting information for technicians
  • Online knowledge bases hosted at manufacturer Web sites
  • Data sheets for technical products such as microprocessors
  • Phone or Web directories that contain demographic and contact information

4.4 Size of the technical content edition

You can consider several metrics concerning the size of the technical content edition.

Number of document types 17:
  • Base edition: 4
  • Technical content edition: 13
Number of element types 440:
  • Base: 189
  • Technical content: 251
Number of pages of PDF version of the specification 867:
  • TOC and introduction: 26
  • Overview, features, and examples: 178
  • Element definitions: 340
  • Appendixes: 323

5 All-inclusive edition

The all-inclusive edition of the DITA specification is the largest edition. It is designed for implementers who want all OASIS-defined specializations, as well as users who develop learning and training materials.

Block diagram that illustrates the components of the three editions of the DITA specification, and the subset relationships between the three editions. The base edition ('part 1') contains the base architecture, which includes map, topic, subject scheme, and DITAVAL. The technical content edition ('part 2') contains the base architecture plus the technical content specializations, which include concept, task, reference, book map, glossary, classification map, machine industry, and troubleshooting. The all-inclusive edition ('Part 3') contains the base architecture, the technical content specializations, and the learning and training specializations. Portions of this diagram that are specific to the all-inclusive edition are highlighted and bold, while others are dimmed, to signify that this is the all-inclusive edition of the specification.

5.1 What is in it?

The all-inclusive edition contains the learning and training document types, in addition to those from the technical content edition.

Topics

The all-inclusive edition includes these learning and training topic types:

Learning assessment
A specialized topic that presents assessment items to measure progress, encourage retrieval, and stimulate reinforcement of the learning content. Although it includes structure for objectives, duration, interaction and summary, the primary use is to contain interactions. The OASIS-defined interaction types are: True/False, single select, multiple select, sequencing, matching, hotspot and open question (essay). When sequenced in a learning map, such material can be organized into quizzes, tests or exams and presented before the content as a pre-assessment or after the content as a post-assessment checkpoint or test.
Note: Any DITA topic type can be configured to include assessment items. This makes it possible to include quiz items directly in a learning content topic or in a prerequisite section of a task topic, for example.
Learning base
A topic that provides the set of common elements that are used in the other learning topic types. This topic also provides a base for creating additional specialized topics for learning content. For example, a DITA practitioner can specialize learning base to create a structure for exercises.
Learning content
A specialized topic that provides learning content and includes structure for introduction, challenge, instruction, objectives, and duration. A learning content topic also can directly reuse content from other content (including task, concept, and reference topics) that supports the objectives declared in the learning overview.
Learning overview
A specialized topic that introduces a set of learning content and identifies the learning objectives and other information that might be helpful to the learner, such as prerequisites, duration, intended audience, and useful resources.
Learning plan
A specialized topic that describes learning needs and goals, instructional design models, task analyses, learning taxonomies, and other information that might be useful in the lesson planning process.
Learning summary
A specialized topic that recaps content and provides context, guidance, and additional resources to reinforce learning and long-term memory. Specifically, it includes structure for summary, objectives, review, next steps, and useful resources.

Maps

The all-inclusive edition includes these learning and training maps:

Learning book map
A specialized book map that includes specialized topic references to organize and sequence learning content for book-oriented publications. It extends the book structure provided in the technical-content book map to include learning metadata in the book map metadata, references to learning object and learning groups, and references to learning object and learning group maps.
Learning group map
A specialized map that stores a discrete set of related learning objects as a separate object. You can reference learning group maps from other learning group maps, learning maps, or learning book maps.
Learning object map
A specialized map that stores a discrete set of learning content to support learning objectives as separate objects. You can reference learning object maps from learning group maps, learning maps, or learning book maps.
Learning map
A specialized map that includes specialized topic references to organize and sequence content as learning objects and learning groups for non-book-oriented learning delivery. It extends the map structure provided in the technical-content map to include learning metadata in the map metadata, references to learning object and learning groups, and references to learning object and learning group maps.

Learning metadata

The all-inclusive edition also includes specialized DITA metadata that can be used to specify characteristics of the learning content. This learning metadata is modeled on industry standards; it is available for use in both the learning topics and learning maps.

5.2 Audience

The all-inclusive edition is designed for authors and publishers who develop and deliver well-structured, modular instructional materials. It provides a framework for using a learning objects approach to organize and sequence content as a learning deliverable.

Users of the all-inclusive edition might include:

  • Instructional designers and course developers for corporate or commercial training materials
  • Teachers in K-12 schools who need easy templates for creating lesson plans and classroom materials, including quizzes and other checkpoints
  • College instructors who organize lectures and require easy publishing to slides and Web sites
  • Textbook publishers who collect contributions from diverse authors and merge them into new deliverables
  • Online course contributors who need simple authoring templates that are tightly matched to specific delivery formats

5.3 What can this edition be used for?

This all-inclusive edition can be used to author and deliver instructional materials that are used in K-12 education, corporate training, textbook publishing, online courses, educational testing, and more.

Examples of such content and specializations might include the following items:

  • Printed textbooks
  • Supporting training materials, including student materials, instructor guides, syllabi, and mobile app content
  • Assessment items for quizzes, exams, and certification test banks
  • Lesson plans that address specific learning objectives and include supporting task, concept, and reference content
  • Online courses that are integrated with learning management systems
  • Electronic textbooks that include multimedia and interactive quizzes
  • Research proposals, academic papers, theses, and other reports

5.4 Size of the all-inclusive edition

You can consider different metrics concerning the size of the all-inclusive edition.

Number of document types 26:
  • Base: 4
  • Technical content: 13
  • Learning and training: 9
Number of element types 621:
  • Base elements: 189
  • Technical content elements: 251
  • Learning and training elements: 181
Number of pages of PDF version of the specification 1,199:
  • TOC and introduction: 25
  • Overview, features, and examples: 186
  • Element definitions: 463
  • Appendixes: 525

Appendix A Acknowledgments

The following individuals participated in the creation of this document and are gratefully acknowledged.

  • Robert Anderson, IBM
  • Don Day, Individual member
  • Kristen James Eberlein, Eberlein Consulting LLC
  • JoAnn Hackos, Comtech Services, Inc.
  • Dick Hamilton, Individual member
  • Nancy Harrison, Individual member
  • John Hunt, IBM
  • Eliot Kimber, Individual member
  • Tom Magliery, JustSystems Canada, Inc.
  • Chris Nitchie, Oberon Technologies Inc.
  • Michael Priestley, IBM
  • Keith Schengli-Roberts, IXIASOFT
  • Eric Sirois, IXIASOFT
  • Amber Swope, Individual member
  • Bob Thomas, Individual member

Appendix B Revision history

The following table contains information about revisions to this document.

Revision Date Editor Description of changes
01 23 August 2015 Kristen James Eberlein Created stub files for working draft.
02 6 October 2015 Kristen James Eberlein Generated working draft 01.
03 8, 17, 18, and 20 October 2015 Kristen James Eberlein Changes made to resolve DITAweb comments. Generated working draft 02.
04 21-28 October 2015 Kristen James Eberlein Changes made to resolve DITAweb comments. Generated working draft 03.
05 29 October 2015 Kristen James Eberlein Changes made to resolve review comments and standardize use of terminology. Generated working draft 04.
06 3 November 2015 Kristen James Eberlein Generated working draft 05.
07 12 November 2015 Kristen James Eberlein Generated working draft 06.
08 05 January 2016 Kristen James Eberlein Generated committee note 01 for posting on OASIS Web site.