DITA Wiki Knowledgebase

Darwin's tool-adapted

Browse, edit, and add to this collaborative knowledgebase of information on using and understanding DITA.

Blue links point to existing wiki pages. Red links represent suggestions for pages where you can be the first to add content.

The DITA Maturity Model

About the DITA Maturity Model Community
- Introduction to the Maturity Model
- Level One: Topics
- Level Two: Scaleable Reuse
- Level Three: Specialization and customization
- Level Four: Automation and integration
- Level Five: Semantics on Demand
- Level Six: Universal semantic ecosystem
- DITA Maturity Model Reference Table
Usage and Copyright Information
Resources for Beginners with the DMM
- DITA Maturity Model Q&A

DITA Specializations Development

DITA Standards Development

This page provides an outline of Wiki pages only; see the Site map for a view of the entire site.

Setting up DITA

Capabilities of DITA

Supported output formats

The DITA Open Toolkit can produce output in the following formats:

It can also be extended to produce output in arbitrary formats.

See Portuguese translation of this page.

Introduction to specialization

Specialization is the process by which new designs are created based on existing designs, allowing new kinds of content to be processed using existing processing rules.

It is the means by which the standard DITA language may be extended for new semantic or structural roles.

Specialization allows you to define new kinds of information (new structural types or new domains of information), while reusing as much of existing design and code as possible, and minimizing or eliminating the costs of interchange, migration, and maintenance.

Specialization may be used to introduce new map types, information types, or domains. An example of a map specialized for a specific application is the Bookmap specialization provided as part of the OASIS DITA 1.1 Standard. An example of a topic specialized for a particular role is message specialization (provided as a msgref plugin of the DITA Open Toolkit). An example of a community-prescribed domain specialization is the hazard domain proposed for DITA 1.2 by the Machine Industry Specialization Subcommittee of the OASIS DITA TC.

Community specialization plugins.

Besides those specializations created as OASIS Standards under the auspices of the OASIS DITA Technical committee, specializations have also been created as community plugins for the DITA Open Toolkit and as file uploads at sites such as the Yahoo! dita-users forum. In addition, many companies have developed specializations that are used internally, and sometimes shared by arrangement with business partners. Finally, some businesses have developed specializations that represent internal business process or workflows; these are usually trade secret assets of those businesses. However, all follow the same methodologies, which means that all such DITA content is interchangeable and (with the appropriate DTDs and processing overrides) interoperable in processing with other content producers or publishers.

Other examples of popular specializations include:

Taxonomies and subject classification (a downloadable plugin of the DITA Open Toolkit)
Learning and Training specialization (a comprehensive suite of specializations developed by a community subcommittee of the OASIS DITA TC)
Troubleshooting specialization (for example, for service manuals)

Specializations may support particular subject matter areas, such as:

Hand-held device manuals and/or content

A comprehensive description of a specialization would include, directly or via links:

Purpose and description
Schema and/or DTD specification files
Sample source code
Sample output

An example of a specialization with all these components that works as a plugin of the DITA Open Toolkit is the music specialization.

Working with DITA

Writing DITA topics

DITA topics are the basic units of DITA content.

Topics are the basis for high-quality information. Each topic is organized around a single subject or answers a single question.

Each topic is typically authored as a unit. It consists of a title, which captures the subject of the topic, and further content.

As stated in the essay paper: Introduction to the DITA architecture, DITA topics are organized by DITA maps. It is also possible to nest sub-topics within a topic. Specialization enables the creation of specialized topics and other units of content that are tailored to particular structural requirements. Content referencing (conref) enables fragments of content to be reused from a single source. Conditional processing permits a single source to support the needs of multiple audiences.

The architectural specification describes topics and information typing at

http://docs.oasis-open.org/dita/v1.1/CS01/archspec/topicover.html.

A 5-minute tutorial on DITA Topics is available as a Flash animation.

Editors for the Architecture area:

Working with maps

DITA maps collect and organize references to DITA topics to indicate the relationships among the topics. They can be used to identify the topics you want to include in a deliverable, and to create tables of contents and related links for the information.

Maps can organize topics into hierarchies, tables, and groups, and also have special elements for referencing other maps. You can use multiple maps to pull different deliverables out of the same set of topics, and to separate the concerns of managing deliverables and architecting information from the concerns of topic authoring.

The architectural specification describes DITA maps and relationship tables at

http://docs.oasis-open.org/dita/v1.1/OS/archspec/dita_spec_23_maps.html.

For a practical approach to setting up relationship tables, see

http://dita.xml.org/improving-relationships-relationship-tables

Controlling heading hierarchies using ditamaps

People often ask what to do to make extra headings and levels of hierarchy appear within a table of contents.

A common misconception is that if a map includes a submap, the title of the submap will appear as an extra heading in output. This does not occur. Also, the topics within the submap appear at the same hierarchy level as other topics that are peer to the submap itself; being in a submap does not cause extra "indenting".

To add an extra heading to a map, a good method is to use a <topicref> element pointing to a topic that contains a title and nothing else. This method is easy to manage for translation.

Another method is to use the <topichead> element. This element did not appear in PDF output using previous versions of the DITA Open Toolkit. However, version 1.4 of the DITA Open Toolkit does create headings from <topichead>.

Tools for modeling maps

The Information Architecture Workbench (formerly IBM Task Modeler) enables you to analyze the organization of your content and creates a corresponding DITA map along with stub topics for to-be-developed topics in the map.

This tutorial provides a quick but comprehensive introduction to using the IAWB to analyze and create a complete map of a sample scenario: IAWB Handout by Ben Welman.

Editors for the Architecture area:

Improving Relationships in Relationship Tables

A team encounters quite a few challenges when transitioning from unstructured to structured writing. For my team, the struggles associated with learning DITA and following the DITA structure were minor compared with the challenges presented by corralling hundreds of individual topics into a logical hierarchy. The biggest challenge we faced was managing topic relationships.

In DITA, related topics can be managed either in the DITA topics themselves, or via DITAMAPs using relationship tables <reltable>.

While topic relationships can be stored in the topics themselves, as products evolve and user interfaces change, a topic that was required for release 1.0 of a product may no longer be needed in release 2.3. If related topics are maintained at the topic level, removing a topic that is no longer part of the system may involve modifying the related topics of a dozen different DITA files.

However, if related topics are managed using a relationship table in a DITAMAP, removing a topic that is no longer needed involves changing only one file. Relationship tables can be used to easily manage the related topics that are associated with each DITA topic.

After doing a lot of research into relationship tables, my team nearly abandoned the effort because mapping a large number of topics in the standard three-column relationship table was too complex. However, once we realized that a four-column approach was much more effective in creating and maintaining the relationships between DITA topics, our information modeling and online help creation process became much easier to manage.

Example Files

To illustrate the benefits of a four-column relationship table, the following example topics will be used.

Concept Topics

The following concept topics are designed to introduce the subject matter to the reader. These topics will cover information ranging from, "What is it?" to "Why should the reader care?"

What is a user? (user_c.dita)
What is a role? (role_c.dita)
How are users and roles related? (user_role_c.dita)

Task Topics

The following task topics are designed to walk the user through a procedure that goes from step 1 to step N, with the end result being the successful completion of the task at hand.

Create a new user account (user_create_t.dita)
Edit an existing user account (user_edit_t.dita)
Create a new role (role_create_t.dita)
Edit an existing role (role_edit_t.dita)
Associate a user account with a role (user_role_associate_t.dita)

Reference Topics

The following reference topics are designed to support the user in completing a task. For example, if step 3 of our task instructs the user to complete field xyz, the reference topic for that window will describe field xyz and include supporting background information that may not appear in the task.

User Account window details (user_r.dita)
Role window details (role_r.dita)

Desired Outcome

Using a standard three-column relationship table and a four-column relationship table, the following relationships will be applied to each topic in the example documentation set:

Standard Three-Column Relationship Table

Each row in a relationship table defines an individual set of relationships between topics. In the relationship table diagram below, there are seven rows that are used to define the relationships between ten different topics. The difficulty in dealing with this type of relationship table is that the relationships for some topics are defined in multiple rows. So when a topic relationship changes, the writer maintaining the DITAMAP must perform a detailed analysis of the relationship between topics in several rows to enact a change.

In DITA, these relationships are expressed as follows:

Four-Column Relationship Table

While the four-column relationship table below has three more rows than the standard three-column relationship table, the larger table makes it much easier to maintain the relationships between the various relationships between the topics. In the example below, when a topic relationship changes, the writer can simply locate and modify a single row that defines the links for that topic.

In DITA, these relationships are expressed as follows:

Conclusion

Using a four column relationship table in our SunGard Higher Education DITAMAPs, we are able to easily maintain the relationships between hundreds of topics authored by a distributed writing team. Each team member can modify the specific row that applies to the topic in question without having to analyze the relationships of any other topic.

While proper up-front planning is still vital to assign topic relationships, knowing that each source topic is always located in the first column and all target topics can be found in columns based on the topic type has made the job of maintaining those relationships much easier. -->

-Zak Binder
Advisory Technical Writer
SunGard Higher Education
zak.binder@sungardhe.com

Working with content references (conref)

Content referencing (conref) is a convenient DITA mechanism for reuse of content from other topics or maps. A fragment of content in one topic or map can be pulled by reference into any other topic or map where the content is allowed. To create the reference, start by creating an empty element of the type that you want to pull in, and then use the element's conref attribute to provide the target's location.

The architectural specification describes content referencing at:

http://docs.oasis-open.org/dita/v1.0/archspec/conref.html

The language specification describes the syntax of the conref attribute at:

http://docs.oasis-open.org/dita/v1.0/langspec/id-atts.html

Editors for the Architecture area:

Working with conditional text

Conditional processing, also known as profiling, is the filtering or flagging of information based on processing-time criteria. The filtering mechanism first matches against the criteria, and then takes a specified action.

DITA provides several built-in attributes to hold the values for filter criteria for an element. These are:

audience
platform
product
otherprops
rev (for flagging only)

It is possible, for example, to specify the platform or audience that a particular paragraph applies to. The values of these attributes can then be leveraged by any number of processes, including filtering, flagging, search, and indexing.

There is a proposal for DITA 1.1 that will enable specializers to define their own metadata attributes for use in conditionally processing content.

The architectural specification describes conditional processing at

http://docs.oasis-open.org/dita/v1.0/archspec/condproc.html

Editors for the Architecture area:

Publishing with the DITA Open Toolkit

The DITA Open Toolkit, or DITA-OT for short, is a set of Java-based, open source tools that provide processing for DITA maps and topical content. You can download the DITA-OT and install it for free on your computer, or you may already have a copy bundled together with your authoring tool or CMS.

The DITA-OT transforms DITA content (maps and topics) into publishing deliverable formats such as web (XHTML), print (PDF), and Help (CHM and Eclipse). Output files are generated in your file system, in a directory of your choosing. During the publishing process, the toolkit runs a set of "pre-process" routines that resolve conref, keyref, and implement several other standard DITA behaviors.

If you do not have a tool that embeds the toolkit, you will need to install it first; instructions are available here: Installing the DITA Open Toolkit.

Using your help authoring tool to publish

The OT is integrated into many authoring tools (e.g.,FrameMaker, <oXygen/>, XMetaL) and content management systems (e.g., Astoria, Bluestream, IXIASOFT, XyEnterprise). Most of these tools provide their own menus or GUIs to interact with the toolkit. Consult your tool's documentation to find out if such tools are available.

Publishing with other GUI tools

There are currently two external GUI tools that may be used to run a toolkit build. These tools are not maintained by the DITA-OT developers; they are created and maintained by users outside of the core development team.

"DITA Open Toolkit GUI" is a simple, open source Java-based GUI that allows you to select an input map, DITAVAL filter file, output directory, and transform type. The tool is hosted at SourceForge: http://sourceforge.net/projects/ditaotgui/
WinANT Echidna is a Windows-only tool that provides access to many more toolkit options. It also allows selection of different skins, so that common sets of options or style branding may be saved or reused. This tool is not open source, but the binary is available for free at SourceForge: http://sourceforge.net/projects/winant-echidna/

Publishing with Ant

For those not using a GUI or authoring tool, the best long term approach to builds is to use Ant. An Ant build file provides you with an easily repeatable build; the time investment is entirely in the initial definition of the build file.

The toolkit includes several sample Ant files in the samples/ant_sample/ directory. When creating your first Ant build, it's a good idea to copy the most appropriate build file to a new location, edit it to change the input file and base directories, and add any additional options as needed. A good current resource for available Ant parameters is the "Ant Quick Start Guide" (http://sourceforge.net/projects/antquickstartgu/); that information is currently being updated and should be integrated into the DITA-OT's doc/ directory sometime in July or August 2010.

Publishing using the Ant Demo

The toolkit also comes with a demo Prompted Build using Ant; this method prompts for the input file, output directory, and transform type, but does not allow access to any other options. To run the demo, run the following command from a DOS prompt in the root directory of the toolkit:

ant -f build_demo.xml

Publishing with the Java command line

The final way to run a build is with the Java command line. This is simply a Java based wrapper that takes in a list of parameters, creates an Ant build file, and then runs an Ant build as described above. The primary purpose of this build method is for one-time builds or for getting to know the toolkit, because it allows access to most processing options without the need to create an Ant file. Of course this method may be used to run any number of builds, but those concerned about memory usage should know that this is no different than running an Ant build together with a small extra Java process.

To get a list of all options available to the Java command line, run the following from the root directory of the toolkit:

java -jar lib/dost.jar

A full build using the shipped sample files would look something like this, which uses the /i parameter for the input file, /outdir for the output directory, and /transtype to select an output type of XHTML:

java -jar lib/dost.jar /i:samples/hierarchy.ditamap /outdir:out /transtype:xhtml

Other resources:

Overview page for information about The DITA Open Toolkit
Descriptions of the available DITA-OT Packages
Installing the DITA Open Toolkit
Tips for debugging PDF issues

Simple Interface For Plugin Installation and Upgrade

Problem: Manual Installation Process

Installing a plugin takes two or three steps, depending upon the platform and installed software.

Unzip the plugin package
Copy the generated directory into the “demo” or “plugins” folder
Run the integrator task

Steps 1 and 2 may be combined on many platforms, if the user knows how to “target” the unzip of a directory appropriately.

This process is actually pretty error prone. Reported user mistakes include:

creating a directory and then unzipping the package into it (resulting in an extra directory)
running the integrator task in the wrong directory

Problem: Automated Installation Process

A software developer or system administrator wishes to make scripts that will automatically install a set of plugins. Today, this installation process necessarily depends upon the directory structure of the DITA Toolkit. This makes reorganizations of the toolkit potentially backwards incompatible.

Proposal

Given a properly configured DITA toolkit, installing a plugin should be a single step, like

java -jar lib/dost.jar /plugin:”c:\My Download Files\FrameMaker_adapter.zip”

No matter what the directory structure of future DITA toolkits, this command line will remain invariant and will copy the right files to the right places.

This implies a fixed structure for plugins. The proposed structure is as described below.

Plugin Structure

A DITA toolkit plugin is a zip file consisting of a single top-level directory. This top-level directory must contain a file called “plugin.xml”. It will typically contain main other files but this standard does not address the structure of those files.

DITA Community

List of organizations using DITA
Examples of documents created in DITA
List of speakers for DITA presentations
DITA user groups
DITA Conferences
Blogroll
Testimonials from organizations using DITA 1.2
HAWEBS.NET - DITA Community (Simplified Chinese)

List of speakers for DITA presentations

This page provides a resource for conference organizers, user groups, and others looking for DITA presentations at public events (including webinars).

If you are available and qualified to speak on DITA, please list your name under the appropriate subhead below (User, Vendor, or Consultant). Include the DITA topic areas on which you can speak, any regional preferences or restrictions, availability, a link to your bio, contact information and other pertinent details. (To add your name, be sure you're logged in, then select the "edit" tab on this page.)

Users of DITA

Bob Doyle is the founder of DITA Users and five companion sites in support of DITA (DITA Blog, DITA Infocenter, DITA News, DITA Tutor, and DITA Wiki). He has pioneered inexpensive web-based collaborations for startup virtual communities. He founded CM Professionals in 2004 and developed their techniques for holding meetings online. He has delivered keynote presentations for conferences from his video desktop. He can speak at your meeting as long as you welcome him virtually by Skype and VNC screen sharing or his new Elluminate Academic Office (which supports 25 simlutaneous users). See his blog, and contact him at editor at cmsreview.com.

Dr. JoAnn Hackos, President of Comtech Services, discusses how best to approach a DITA implementation. Her process begins with content restructuring, including minimalism, before any change in technology. She is most influential is helping senior management understand the business benefits of moving to an XML-based standard and outlines four levels of cost savings that organization may achieve with a DITA implementation. http://www.comtech-serv.com

<insert your name and profile here

Vendor representatives

<insert your name and profile here>

Consultants

Comtech Services, Inc. provides a full range of consulting services for organizations wishing to implement the DITA standard. Included in those services are business-case development, reuse strategies, content restructuring, information modeling, stylesheet development, translation and localization strategies, and more. http://www.comtech-serv.com

DITA Standards Development

About the OASIS DITA Technical Committee and Subcommittees

The purpose of the OASIS DITA Technical Committee (DITA TC) is to define and maintain the Darwin Information Typing Architecture (DITA) and to promote the use of the architecture for creating standard information types and domain-specific markup vocabularies.

Review the list of organizations that participate in the DITA TC.

Everyone is welcome to join the DITA TC. If you are employed by an existing OASIS member, you can go directly to the DITA TC web site and click on Join This TC. If your employer is not currently an OASIS member, you can find out how to become involved at Join OASIS.

The current work of the DITA TC is made visible through e-mail archives and a TC wiki. A consolidated zip file with all specifications, DTDs, and Schemas for DITA 1.1 is publicly available at dita1.1.zip.

The DITA TC home page also includes links to the public sites for the current subcommittees. All subcommittees operating under the DITA TC are listed on the OASIS DITA TC home page. More information is available about -OASIS DITA TC specialization subcommittees-.

Users may be interested in the mailing lists and additional information listed on the DITA TC web site.

OASIS DITA Learning Content Subcommittee

This page contains information about the work of the OASIS DITA Learning and Training Content Specialization Subcommittee (at http://www.oasis-open.org).

What is the purpose of the committee?

How does it operate?

What methods are available for staying informed about the work of the committee?

What background information is on record?

What work products are publicly available?

What issues is the committee working on?

Who should join and how is that done?

OASIS DITA Machine Industry Subcommittee

This activity will help to galvanize the role of DITA specializations across
industries that have common issues for hardware-related description.
Such as: manufacturing system engineering,
engine- and machine construction, power plant equipments, apparatus
engineering, elevators and escalators etc.

OASIS DITA Semiconductor Information Design Subcommittee

Creating DITA specializations for better information design and interoperability throughout the semiconductor industry.

This subcommittee represents a community of interest within various semiconductor companies who believe that there is value in creating a DITA specialization for the industry. Not only will this enable better integration with the development of the OASIS DITA Standard, but will provide an opportunity for

Reduce in-house development costs
Reduce the work associated with integrating third party IP
Increase customer reach, and enable customers to find products quickly
Provide end-customers with more value

OASIS DITA Translation Subcommittee

DITA Translation Subcommittee.

JoAnn Hackos, joann.hackos@comtech-serv.com, Chair
Gershon Joseph*, gljoseph@yahoo.com, Secretary

Goals:

1) Develop an effective liaison with the OASIS XLIFF technical committee and the W3C ITS working group so that the DITA TC can work together with those interested providing for the needs of the information-development community from authoring through localization to the production of final deliverables in multiple languages.

2) Establish guidelines that promote best practices for authoring, workflow, and tools that allows information to move seamlessly from original authors and editors through translators and production specialists handling the intricacies of multiple languages and cultures.

3) Add to the various specifications methods that will help vendors and service providers comply with DITA and translation-oriented standards.

4) Add a DITA to XLIFF to DITA tool set to the DITA Open Source Toolkit so that content can move seamlessly along the full information development life cycle.

DITA OT 1.3 Issues tracking

NOTE: Version 1.3 was released in 2006. This information should no longer be considered up to date. Up to date information on the toolkit can be found here: The DITA Open Toolkit

The next major release (1.3) of the DITA Open Toolkit is being evaluated for scope and schedule. The project team has been tracking requirements coming from the OASIS DITA TC, the dita-users support forum, and among the dita-ot developer community discussions. The open requirements are listed below. The purpose of this document is to host separate design discussions for each of these items. Out of these discussions, the project team will assess the relative priorities and available resource (contributors and code, for example) that can be applied to the proposed schedule.

Don Day, DITA OT Team Lead

Tentative schedule:

Task_Name, Duration, Start, Finish

Coding, 1 Month, start of July, around 06-8-10

Test Execution, ~ 1 Month, Mid July, around 06-8-22

Release Prep, ~ 1.5 weeks, around 06-8-23, end of August

Release, , end of August, end of August

Design discussions for the proposed items (tentative list) are here:

1. Support for DITA 1.1/bookmap (stakeholders: OASIS DITA TC and popular community request)

2. Eclipse integration (stakeholders: community and dev team)

3. Incremental builds (stakeholders: advanced users, dita-ot developers)--Deferred to 1.4 to gather more case studies, understand requirements better.

4. GUI/usability (stakeholders: dita-user community, loudly heard at recent DITA conferences)--Revised to focus first on installability, defer GUI to related projects (much as editor vendors provide their own GUIs, in effect).

5. Fix topicmerge (stakeholders: dev team, judged to be strategic and a necessary base for the new bookmap support)

6. Fix indexing (stakeholders: known lack of full support for all users, languages)

7. Fully enable the XML catalog resolver (stakeholders: )

8. Ant refactoring (stakeholders: dev team, judged to be strategic for toolkit maintenance and future plugin development)

9. Document refactoring (stakeholders: end-users, other document authors)

If you have requests for other issues that you feel are critical for 1.3, please send them to Don Day (dond at us.ibm.com) so that I can compare them with other reports. The agenda for 1.3 is already very large for an aggressive schedule, therefore I would need to understand the value and justification of any new request for the larger community in order to assess it against these that have already been identified. Thanks!

Suggesting enhancements to the DITA Standard and Toolkit

This page is intended to facilitate collaboration on ideas for enhancing the DITA specification and the Open Source DITA tools. Add your ideas for new features and capabilities in DITA, and suggestions for improving the flexibility and robustness of the architecture.

Enhancements to the DITA Standard

Please note that actual work on creating or revising the DITA OASIS Standard or specification must take place within the OASIS DITA Technical Committee, which operates under the open OASIS Technical Process. This process, which governs issues such as transparency, contributions, licensing, participation, and disclosure, assures that OASIS Standards remain widely available and safe to implement, produced in an open, democratic, and accountable method.

While this page is a great place to get an enhancement idea started and to encourage informal collaboration, once the idea is ready to be advanced, the discussion should move to the formal OASIS Technical Committee Process. All those who wish to participate in standards development or more closely observe this work are strongly encouraged to join OASIS. A variety of membership levels are offered to assure that everyone affected by standards may contribute to their creation.

You can also provide feedback, such as feature requests for additions or changes to the DITA specification, through the OASIS DITA Comment Form. All comments received via that form are documented and reviewed by the OASIS DITA Committee members and publicly archived.

Enhancements to the DITA Toolkit

The DITA Open Toolkit is an open source project that anyone can contribute to. The best place to request enhancements to the DITA Open Toolkit is by opening a Request For Enhancement (RFE) in the RFE tracker at the DITA-OT Project page: http://sourceforge.net/projects/dita-ot/

Future approaches to subject classification

There are two main approaches to subject classification currently being explored for future use in DITA, which this page will call the map-based approach and the metadata approach.

In the map-based approach, a taxonomy is represented using a hierarchy in a DITA map. Each member of the hierarchy is a specialization of the <topicref> element. Each <topicref> element points to a topic that describes the subject of that node of the taxonomy.

In the metadata approach, the <data> element (which is being introduced in DITA 1.1) is used to record properties. The property stated in a <data> element is considered to apply to:

the enclosing element (the default)
another element (if a URI is specified)
an external object (if a sub-element is used and a URI is specified in the sub-element)

When the <data> element is used within content, the property that it states is considered to apply to the directly enclosing content element. When the <data> element is used in metadata contexts, the property that it states is considered to apply to the nearest enclosing content element (such as <topic>).

Broader topics:

DITA 1.2 CD 03 review

The DITA TC wants to ask for additional feedback on the DITA 1.2 specification draft. The formal 60-day review is slated to close this coming Sunday, 5 September 2010.

Download the DITA 1.2 specification draft

HTML: http://docs.oasis-open.org/dita/v1.2/cd03/spec/DITA1.2-spec.html (Authoritative version)

PDF: http://docs.oasis-open.org/dita/v1.2/cd03/spec/DITA1.2-spec.pdf

CHM: http://docs.oasis-open.org/dita/v1.2/cd03/spec/DITA1.2-spec-chm.zip

DITA: http://docs.oasis-open.org/dita/v1.2/cd03/spec/DITA1.2-spec.zip

How to comment on the DITA 1.2 specification draft

To comment on the draft, you need to subscribe to the dita-comment mailing list. For information about subscribing to this list, see http://www.oasis-open.org/committees/comments/index.php?wg_abbrev=dita . If you are interested in seeing comments that have already been made about the draft, you can read the dita-comment archives at http://lists.oasis-open.org/archives/dita-comment/; the comments about the draft are in directories for July 2010 (201007) and August 2010 (201008).

For more information about the status of DITA 1.2

The DITA Adoption TC has published a feature article about the status of DITA 1.2. You can download it from http://dita.xml.org/resource/dita-12-feature-article-status-update

We rely heavily on the involvement of the user community and implementors to help us drive development of the DITA standard and its documentation – please help us out!

About DITA

The DITA OASIS Standard builds content reuse into the authoring process, defining an XML architecture for designing, writing, managing, and publishing many kinds of information in print and on the Web.

The standard is advanced through an open process by the OASIS DITA Technical Committee, a group that encourages new participation from developers and users.

DITA 101

The DITA OASIS Standard defines an XML architecture for designing, writing, managing, and publishing technical documentation in print and on the Web. DITA (commonly pronunced dit'-uh) builds content reuse into the authoring process for document creation and management.

Topic-Based Authoring

Focusing on a common topic model as a conceptual unit of authoring, DITA provides a core set of topic types derived from concept, task, and reference. DITA defines a specialization mechanism for extending markup to represent either new topic types or new domains of markup common across sets of topic types. DITA maps can combine topics into various kinds of deliverables. Content can be shared among maps or topics. Class-based processing ensures new specializations can be supported with existing tools, speeding the testing and adoption of new designs.

With DITA, all content is inherently reusable. That's because DITA's strength lies in a unified content reuse mechanism that enables an element to replace itself with the content of a like element, either in the current topic or in a separate topic that shares the same content models.

Supporting Multiple Deliverables and Publishing Channels

DITA enables organizations to deliver content as closely as possible to the point-of-use, making it ideal for applications such as integrated help systems, web sites, and how-to instruction pages. DITA's topic-oriented content can be used to exploit new features or delivery channels as they become available.

DITA enables highly automatable processes, consistent authoring, and enhanced applicability to specific industries. Content owners benefit from industry support, interoperability, and reuse of community contributions. At the same time, content owners address the specific needs of their business or industry.

Benefits

DITA can be used to...

Enable effective information management
Improve information authoring models
Reuse content in different combinations for a variety of deliverables
Create online information systems, such as User Assistance (help) and learning modules (training)
Design minimalist books for easier authoring and use

Get Involved

DITA is advanced by the OASIS DITA Technical Committee. Its members include representatives of:

XMetaL

...and other XML tools vendors, consultants on Information Architecture and Content Management Systems (CMS), and users.

Participation remains open to all organizations and individuals. A wide variety of membership levels and rates are offered to ensure all those who are affected by DITA have a voice in its development. See Join OASIS or contact member.services@oasis-open.org for details.

Why DITA?

For some, perhaps the real question is Why XML? (or What is XML?), but assuming you have answered those questions (and are using XML), then the next step is to locate an appropriate data model for your content. This is an important step because you will spend a lot of time and money developing processes and selecting tools to support your chosen data model. XML, by definition, is extensible and allows you to create any valid structure that suits your needs, but before you decide to develop your own, consider the pre-existing options (see Don't Invent XML Languages for a discussion on why not to develop your own). If you can leverage and build on top of someone else's work, why not?

DITA is a data model for authoring and publishing topic-based content. It was developed by IBM for internal use and has since been released to the open-source community (now under the guidance of OASIS). This architecture and data model were designed by a cross-company workgroup representing user assistance teams working throughout IBM. After an initial investigation in late 1999, the workgroup developed the architecture collaboratively during 2000 through postings to a database and weekly teleconferences. Since that time IBM has migrated thousands of pages of content to DITA.

But, why DITA?
Well, assuming your content fits into the topic-based data model, DITA's increasing popularity means that more and more authoring and publishing tools will be developed to support that model. The DITA Open Toolkit allows you to generate many popular output formats (HTML, HTML Help, PDF, Java Help, etc.) from DITA-based content. If you develop your own data model, you'll have to pay to develop those transformations. DITA's modular architecture, supports efficient reuse of content at the word, phrase or topic level. DITA also has the concept of "specialization," which allows you to develop elements of your own that are based on core DITA elements. This helps you to customize DITA to support your particular types of content while continuing to take advantage of the base DITA tools and transformations.

Learn more
The following articles provide additional information:

Going DITA - by Constantine Hondros Oct. 12, 2005 03:21 PM
This blog provides insights from a software developer currently involved in a project to migrate a mission-critical document corpus to the DITA architecture.
The Holy Grail of Content Reuse: IBM's DITA XML - Cover Pages, April 25, 2003
Robin Cover offers a clear, concise overview of DITA basics and benefits in this report.
Is DITA Going to Tip? - Center for Information-Development Management, JoAnn Hackos, PhD, Dec. 2005
This article explores the reasoning behind the adoption rate of DITA and other publishing technologies.
Why use DITA to produce HTML deliverables? - IBM developerWorks, 07 Oct 2003, Updated 28 Sep 2005
This article described advantages DITA provides for producing HTML content -- including easy global changes, portability through standards, superior linking and Web management, conditional processing, content and design reuse, and better writing through focused content.
Introduction to the Darwin Information Typing Architecture - IBM developerWorks, 01 Mar 2001, Updated 28 Sep 2005
This document is a roadmap for DITA: what it is and how it applies to technical documentation.
DITA webinar, "What You Should Know About DITA" - Arbortext, April 28, 2004
DITA Q&A .. What is DITA?; What’s so great about DITA?; Does DITA allow for use of a custom DTD?; How much of the flexibility and reuse demonstrated during the presentation was due to DITA and how much simply to having XML source?; and more.

Other

Edit and add other wiki pages to this section.

Topic-based authoring

Topic-based authoring has been a mainstay of technical information development since we first began developing help systems. We learned quickly enough that we couldn't split our existing books into help topics by making every heading level a new help page. Information originally designed with a narrative flow no longer made sense nor assisted users in finding exactly the content they needed. We had to rethink the type of information that our help systems should include and create a new set of standards for its development. The result is topic-based authoring.

Authoring in topics provides information developers with a way to create distinct modules of information that can stand alone for users. Each topic answers one question: "How do I ...?" "What is ...?" "What went wrong?" Each topic has a title to name its purpose and contains enough content for someone to begin and complete a task, grasp a basic concept, or look up critical reference information. Each topic has a carefully defined set of the basic content units that are required and accommodates other optional content. As information developers learn to author in topics and follow sound authoring guidelines consistently, we gain the ability to offer information written by many different experts that looks and feels the same to the users.

Not only has topic-based authoring become the norm for well-designed help systems, information architects have learned that formulating consistently structured topics facilitates readability and information access in traditional, more linear book structures. Readers are able to identify task-based topics within sections and chapters because the tasks look the same and contain the same essential content units. Readers learn that conceptual and background information is always located in the same position in the table of contents with respect to the tasks. Readers come to depend upon standard reference sections that contain similarly structured details for ease of lookup.

The core information types in DITA support the structures that underlie most well-designed technical information. Any organization that follows best practices in formation architecture will find the core DITA structure a good fit. But they also challenge us to become even more disciplined in structuring information according to a set of carefully defined business rules. The benefit of such disciplined information structuring is the consistent presentation of information that helps you build reader confidence and simplify the reader's task of knowing how to navigate and use your information.

Benefits of topic-based authoring

Authoring in structured topics provides you with a sophisticated and powerful way to deliver information to your user community. You will find benefits that decrease your development costs and time to market, as well as provide increased value to your customers:

Structured topics contain only the information needed to understand one concept, perform one procedure, or look up one set of reference information.

Structured, topic-based authoring promotes consistency in the presentation of similar information.
Topics can be reviewed by subject-matter experts as soon as they are ready. They need be reviewed only once, even if they appear in multiple deliverables, reducing the burden on reviewers.
Topics can be translated before entire volumes are complete, reducing the time to market for global customers. Topics in multiple languages can

be combined into language-specific deliverables without extra desktop publishing time and expense.
Assembling topics into multiple deliverables can be automated, reducing production time and costs.
Consistently structured topics are easier to reuse in multiple deliverables.
Structured topics may be combined in new ways to meet changes in product solutions, work structures, geographies, industries, or other customer configurations.
Topics are easier to update immediately instead of waiting for the next release of an entire library of documents.
Consistently structured topics help users build a firm mental model of the types of information you are presenting.
Consistently structured topics help users navigate more quickly to the information they need.

If one of your business goals is to use information topics in multiple deliverables, you need to build a repository of topics that are clearly defined according to your standard set of information types. Your repository is also characterized by the metadata attributes you associate with you topics.

DITA provides you with such a standard as a starting point. DITA gives you the capability to expand upon its core information types when you need to accommodate the special needs of your customers and your information.

Defining information types for your topics

If your information is like most in the technical information industry, you have a great diversity of structures in your information, especially if those topics are embedded in the threaded, narrative sections and chapters of books. Your first job is to inventory your content to identify its range and diversity.

In most cases, you will find lots of tasks, containing step-by-step instructions for reaching a specific goal. The dominance of the task in technical information is why DITA includes the task as one of the three core information types.

Accompanying tasks, you are likely to find background, description, and conceptual information that explains what something is. DITA labels such supporting information "concepts". You will also find tables, lists, diagrams, process flows, and other information that can be labeled as "reference," the information that no one wants to memorize but must be easy to look up.

Once you have completed your content inventory, you need to carefully analyze the three core information types provided with DITA. The standard structure for task, concept, and reference is presented in the DITA specification. Experiment with accommodating your content to the standard structure. In most cases, your content easily fits into a standard DITA structure.

Where you may encounter difficulties is with the diversity of your own content rather than with the DITA information types. Some of the content in your inventory will not even meet your own guidelines. Often, that content was written by people long gone from your organization or was influenced by subject-matter experts who wanted it their way rather than following your authoring guidelines.

Our recommendation is to focus on the essential underlying structure of your content rather than the idiosyncrasies and accidents of individual writers over the years. If you find an odd structure in a task, for example, ask if that structure is the best way of conveying the information to the user or if the task can be rewritten following the structure of a standard DITA information type. Most of the time, you will find that the standard is the best solution.

One of the more common problems you will find with some of the content you examine is mixed structure. Tasks start out with long discussions of background information. Concepts end up including step-by-step procedures. Tables of reference material end up with concepts in the footnotes or tasks incorporated into table cells.

Although mixed information types are possible in DITA, we don't recommend using them. Consider that by separating information carefully and rigorously into the neat, consistent information-type buckets provided, you will have information that you can present much more dynamically and flexibly to users. If a users wants to know the steps of a task, they won't have to skip over background that they don't want to think about yet. You can refer them to that conceptual and background information through a related-topic reference or a hypertext link rather than embed lengthy conceptual information in the task.

By chunking your information according to well-defined information types rather than combining types randomly, you gain flexibility in distributing your information to people who need it most. You also make the relationships between chunks of information more obvious. If you believe that users will profit from reading background information before performing a task, by using related-topic links, you can ensure that they know about the relationship and why reviewing the concept or background is advantageous.

Adding new information types

Although we find that most technical information fits neatly into the standard DITA information types, we recognize that you may discover that you have special information types that cannot be accommodated by the standard content units or that you want to label those content units with more descriptive XML tag names. At that point, you need to pursue specialization.

Consider an example in the semiconductor industry. A great deal of detailed information about a chip design is contained in an information type called a register description. Although a register description falls into the class of reference information types, it has some very specific and detailed content. By specializing on the standard reference information type, you can build a register description specialization that standardizes the content with appropriate XML elements names, assisting the writers and providing additional metadata to facilitate searches. Many similar opportunities for specialization may present themselves in your content. But be careful to exhaust the possibilities of the standard information types before pursuing the differences.

The more differences you present to writers and readers, the more opportunities there are for confusion. With too many choices of information types, an information developer is more likely to chose incorrectly. With too many subtle differences in the presentation of information, your users are more likely to become confused when they are unable to find the standard set of content that they have come to expect.

This discussion of topic-based authoring is excerpted from

Introduction to DITA: A Basic User Guide to the Darwin Information Typing Architecture, by Comtech Services, Inc.

See Portuguese translation of this page.

Related books (topic-based authoring)

The books listed here contain information relevant to topic-based authoring:

Sissi Closs: Single Source Publishing. Topicorientierte Strukturierung und DITA, Entwickler-Press, 2006

This book describes the Single Source Publishing history and explains the relevant concepts focused on topic-oriented structures. Siss Closs has developed the class concept method with which adequate topic and link types can systematically be developed for any kind of content. In this book, the class concept method is described in detail. In addition, the book contains a DITA short reference.

Jonathan and Lisa Price, Hot Text, New Riders Press, 2002

Hot Text focuses on good writing practices, including topic-based authoring, and applies these to web-based deliverables. It includes XML authoring that is directly applicable to implementing the DITA model.

Robert E. Horn, Mapping Hypertext: The Analysis, Organization, and Display of Knowledge for the Next Generation of On-Line Text and Graphics, Lexington Institute, 1990

Robert Horn is the developer of Information Mapping(tm). Although this book focuses on online information, it is one of the few publically available discussions of the topic-based principles of information mapping. In the book, Horn explains how to chunk, organize, and sequence content.

JoAnn Hackos and Dawn Stevens, Standards for Online Communication, Wiley, 1997

Hackos and Stevens focus on topic-based authoring in the context of online information systems. They include both help and web design in the examples. However, the topic-based authoring principles are central to the writing methods detailed in the book. The authors demonstrate how topic-based authoring differs significantly from book-based authoring.

Kurt Ament, Single Sourcing: Building Modular Documentation, Noyes Publications, 2002

Ament explains in plain language and by example how to develop single source documents. He shows technical writers how to develop standalone information modules, then map these modules to a variety of audiences and formats using proven information mapping techniques.

Gretchen Hargis et al. , Developing Quality Technical Information: A Handbook for Writers and Editors, IBM Press, 2nd edition, 2004

Many books about technical writing tell you how to develop different parts of technical information, such as headings, lists, tables, and indexes. Instead, we organized this book to tell you how to apply quality characteristics that, in our experience, make technical information easy to use, easy to understand, and easy to find.

Developing Quality Technical Information : A Handbook for Writers and Editors

IBM Press Series--Information Management (not DITA but recommended as a good book on "topic based authoring") (Available from Amazon.com.)

Architecture

The DITA Architecture area contains references to specifications and articles that explain the architectural underpinnings of the DITA language.

Introduction to the DITA Architecture

This introduction to the DITA Architecture contains overall technical information about the DITA language and its architecture.

In the DITA architecture, DITA topics are organized by DITA maps. It is also possible to nest sub-topics within a topic. Specialization enables the creation of specialized topics and other units of content that are tailored to particular structural requirements. Content referencing (conref) enables fragments of content to be reused from a single source. Conditional processing permits a single source to support the needs of multiple audiences.

The current version of DITA is specified in the OASIS Darwin Information Typing Architecture (DITA) Standard v1.2. The OASIS DITA Technical Committee is currently working on version 1.3.

The OASIS site http://www.oasis-open.org/specs/index.php#ditav1.2 contains the official versions of the following documents:

http://www.oasis-open.org/standards#ditav1.2

The following article provides additional information:

Introduction to the Darwin Information Typing Architecture - IBM developerWorks, 01 Mar 2001, Updated 28 Sep 2005
This document is a roadmap for DITA: what it is and how it applies to technical documentation.

Editors for the Architecture area:

Previous versions of the DITA specification

The current DITA specification is version 1.1. This page describes previous versions of the DITA specification.

Technical work produced by the OASIS DITA Technical Committee includes:

Committee Draft 1.0.1 of the DITA DTDs and Schemas
The compressed file dita-document-definitions-1.0.1.zip contains version 1.0.1 of the DITA DTDs and Schemas. Version 1.0.1 contains all of the fixes described in this document: Fixes for OASIS DITA 1.0. It also contains a change document 101changes.txt (one for the DTDs, and another for the Schemas). These files list all actual bug changes, including the changed catalog for DTDs. They also contain a pointer to the web page above for a full description of the changes.
DITA OASIS Standard Version 1.0
A consolidated zip file with all specifications, DTDs, and Schemas is publicly available in the documents section dita10.zip.

This document is revision #4 of cd1.zip. The document details page shows the complete revision history.
Previous submissions
The first committee draft (before revision), cd1.zip is still available in the Documents section.

DITA 1.1 versus 1.0

What's new in DITA 1.1:

Version 1.1 of DITA provides enhanced print publishing capabilities with new DITA Bookmap specialization, including extended book metadata. The standard offers more indexing capabilities with new elements for "see" and "see-also" references. It features new elements for defining structured metadata as well as the ability to add new metadata attributes through specialization.

The specification files (HTML and PDF Spec documents, DITA source, DTDs and Schemas) are available here:

http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita#technical

The Overview is a great entry point into the various parts of the DITA 1.1 standard:

http://docs.oasis-open.org/dita/v1.1/OS/overview/overview.html

DITA Wiki Knowledgebase

See also:

Setting up DITA

Capabilities of DITA

Supported output formats

Introduction to specialization

See also:

Working with DITA

Writing DITA topics

Working with maps

Controlling heading hierarchies using ditamaps

Tools for modeling maps

Improving Relationships in Relationship Tables

Example Files

Concept Topics

Task Topics

Reference Topics

Desired Outcome

Standard Three-Column Relationship Table

Four-Column Relationship Table

Conclusion

Working with content references (conref)

Working with conditional text

Publishing with the DITA Open Toolkit

Using your help authoring tool to publish

Publishing with other GUI tools

Publishing with Ant

Publishing using the Ant Demo

Publishing with the Java command line

Other resources:

Simple Interface For Plugin Installation and Upgrade

Simple Interface For Plugin Installation and Upgrade

Problem: Manual Installation Process

Problem: Automated Installation Process

Proposal

Plugin Structure

DITA Community

List of speakers for DITA presentations

DITA Standards Development

About the OASIS DITA Technical Committee and Subcommittees

OASIS DITA Learning Content Subcommittee

OASIS DITA Machine Industry Subcommittee

OASIS DITA Semiconductor Information Design Subcommittee

OASIS DITA Translation Subcommittee

DITA OT 1.3 Issues tracking

Suggesting enhancements to the DITA Standard and Toolkit

Enhancements to the DITA Standard

Enhancements to the DITA Toolkit

Future approaches to subject classification

DITA 1.2 CD 03 review

About DITA

See also:

DITA 101

Why DITA?

Other

Topic-based authoring

Related articles (topic-based authoring)

Related books (topic-based authoring)

Developing Quality Technical Information : A Handbook for Writers and Editors

Architecture

Introduction to the DITA Architecture

Previous versions of the DITA specification

DITA 1.1 versus 1.0

See also: