DITA Wiki Knowledgebase

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

Getting started

Getting started with DITA requires a multi-step process:

Understand the topic-based architecture underlying the DITA model.
Topic-based authoring is the basis of DITA. In order to understand the best approach to DITA, first understand how to work with topics and structured writing.
Create an information model.
This is the best way to provide your employees with a guideline to follow throughout your DITA adoption and implementation process. An information model includes information such as:
- Information Type descriptions
- Content Unit descriptions
- Metadata and folder/repository structure definitions
- Naming conventions
- Document definitions

Read the DITA Architecture and Language Specification to understand how the model works.
For help creating your information model, you may find the DITA Architecture Specification and the DITA Language Specification helpful. The Language Specification provides you with element and attribute definitions you can use as part of the DITA standard. The DITA Architecture Specification provides you with information about the features DITA provides such as content reuse, conditional processing, and specialization.
Inventory your own content and transform it into topics.
In order to fully develop your processes and information model, consider developing a pilot project. Your pilot project should be small enough to not discourage employees and other stakeholders from continuing the project, but also large enough to fully test your content with the DITA model and test your workflow processes. It's best to first inventory your content to identify consistencies in structure and information you can minimalize and reuse. Then, start marking up your content using DITA markup to identify special needs to fit your content.
Download the DITA Open Toolkit and processing information from Source Forge
For processing, you may want to use the DITA Open Toolkit to create PDF, XHTML pages, HTML Help (.chm), Java Help, and Eclipse Help. The DITA Open Toolkit provides processing and rendering techniques to create your output.

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.

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 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>.

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 a "reference implementation" for processing DITA maps and topical content. You can download the OT and install it for free on your computer, to get started with topic-based writing and publishing.

The DITA Open Toolkit is a modest publishing system. The Toolkit transforms DITA content (maps and topics) into publishing deliverable formats such as web (XHTML), print (PDF), and Help (CHM and Eclipse). Your output files are simply generated in your file system. It is up to you to move them to your website, or into your print publishing process.

The OT is integrated into many authoring tools (e.g.,FrameMaker, <oXygen/>, XMetaL) and content management systems (e.g., Astoria, Bluestream, IXIASOFT, XyEnterprise).

If you find installing the OT too difficult, consider a free running version of the DITA Open Toolkit provided as an online software-as-a-service by the DITA Users organization.

There you can have an online workspace folder with DITA docsets from IBM and Comtech Services. Edit the files and build/publish them as web (XHTML), print (PDF), and Help (Eclipse). All your work can be browsed on the web by your colleagues as a portfolio of your DITA work with the OT.

The home page of the DITA Open Toolkit is http://dita-ot.sourceforge.net/. The DITA Open Toolkit Installation Guide, which is on that page, contains a list of supporting open-source software to download, together with a set of versions that are known to be compatible.

The instructions on how to install and use the OT are maintained by Anna van Raaphorst and Dick Johnson as the DITA Open Toolkit User Guide. Note that there are multiple packages available for the toolkit; if you are trying it out for the first time, you probably want to get the "full" package (now called "full easy install") that comes with other required software, and requires less manual setup.

Don Day maintains a DITA Open Toolkit Resources Page.

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

DITA is being deployed worldwide. If your organization uses DITA, please add to this list. (Log in, select the "edit" tab above, and insert your organization in alphabetical order under the appropriate category below.).

See Case studies for detailed descriptions of representative implementations.

Private sector

Adobe (product support content)
Algorithmics (manuals, online help)
Altitude Software (manuals, online help, slides, training guides)
Arena Solutions (manuals)
Autodesk (product support content)
Astoria Software (manuals, online help, tutorials, specifications)
Avaloq Evolution AG (manuals, online help)
Avaya (manuals, online help)
BMC Software (manuals)
Broadridge's SIS (product support documentation)
Business Objects (user documentation, web sites)
CEDROM-SNi (user training materials, reference guides)
Cmed Technology Ltd (user documentation)
Comet Communication GmbH (DITA training, DITA tools training)
Comet Computer GmbH (user documentation, manuals, online help systems, tutorials)
Compuware Corporation (user documentation)
Comtech Services (manuals, quick reference, Flash interactive)
Confiz Solutions (online help documents)
Data Conversion Laboratory, Inc. (Manuals and User Documentation)
DITA Storm (a web-based DITA Editor and Wiki)
DITA Users (DITA training from Authoring to Building)
DITA Infocenter (arch and lang specs, OT guide, in Eclipse Help)
EMC (manuals, online help)
FamilySearch (API documentation, user guides, etc.)
Freescale Semiconductor (user documentation for CodeWarrior tools)
Gambro BCT (manuals, online help, tutorials, specifications)
GE Multilin (manuals, reference guides, online help)
ICOS Vision Systems (manuals)
IBM (manuals and information centers)
Idiom Technologies (manuals, online help, tutorials, specifications)
InfoPros (manuals, online help)
Information Builders (documentation)
Innodata Isogen (manuals, online help, documentation)
Innovatia (manuals, online help, documentation, training)
I PLocks, Inc (manuals, online help, documentation)
Inmedius, Inc. (manuals, online help, DITA-enabled tools)
JustSystems (manuals and online help for XMetaL, requirements and development documents)
Kongsberg Maritime (manuals, online help, documentation)
Lombardi Software (PDF+Eclipse+Web Help +wiki outputs, embedded user assistance, training products)
McAfee, Inc. (installation guides, product guides, online help, release notes)
Moldflow (manuals, online help)
Nexwave-Solutions (manuals, tutorials)
NetApp (manuals, online help)
Nokia (user and development information)
Oracle (user guides and online help)
PCI Geomatics (manuals, reference guides, online help)
Perspectix (product manuals, reference guides, online help)
Pillar Data Systems (manuals, reference guides, online help)
Really Strategies, Inc. (product manuals, training,etc.)
Saba Software, Inc. (manuals, online help)
salesforce.com (Everything - tip sheets, user guides, online help, etc.)
skyBuilders (online training for DITA Users)
Sophos (online help, manuals, training materials)
Sterling Commerce (manuals, online help)
Sybase, Inc. (eclipse user assistance, other product documentation)
Syclo, LLC (all product and development platform manuals)
TANNER AG (manuals, product catalogs, software)
Teradata Corporation (manuals, online help, service guides, training)
Tekelec (manuals, references)
Virtek Vision International Inc. (product manuals, online help)

Public sector

U.S. Financial Accounting Standards Board (FASB) (Codified GAAP standards)

Non-governmental organizations (NGOs)

Universities and Research Centers

Brigham Young University (printed books and online research repository)

DITA user groups

DITA user groups (DUGs) or DITA special interest groups (DIGs) facilitate knowledge sharing among users in specific geographic areas or among those with similar interests.

Regional DITA user groups

If you participate in a DITA user group not listed above, please add a link to your group's homepage. You may also use DITA XML.org to host pages for your DUG.

Virtual DITA user groups

dita-users on Yahoo Groups
DITA Users organization
Facebook DITA group
FrameMaker-DITA on Yahoo Groups
Second Life: Addicted to Reality 13, 27, 24
X-Metal DITA Yahoo Group

If you are aware of other virtual DUGs, please add to this list by selecting the "Edit" tab above.

Potential new DITA user groups

See comments at the bottom of this page. If you're looking for others interested in forming a new group in your local area or within your field of interest, please select the "add new comment" link below. Include your email address to encourage others in your area to contact you.

Research Triangle Park (RTP, NC) DITA users' group

Charter

The purpose of the RTP DITA Users' Group is to facilitate communication and the sharing of knowledge between DITA users in the Research Triangle Park (RTP) area of North Carolina.

Meetings

We meet on the fourth Wednesday of each month from 5:30-6:30 PM. Currently our meetings are held at the following location:

Systems Documentation, Inc
1005 Slater Road, Suite 220
Durham, NC 27703.

Directions to Systems Documentation, Inc.

Communications

We have a Yahoo! Groups mailing list. To join, go to http://tech.groups.yahoo.com/group/rtp-dita/
For more information about the group, you also can contact kjeberle@us.ibm.com.

Upcoming events

January 28: To be determined

Past events

October 22: Crossing Organizational Boundaries with DITA
Presenter: Colleen Smith, Teradata Corporation, Content Management Information Architect

September 24: DITA, Metada, and Taxonomy
Presenters: Robert Berry, Mike Harris, and Paul Arellanes (IBM). Jointly sponsored with the Central TX DITA User Group.

August 27: DITA 1.2: Understanding the upcoming release
Presenter: Robert D. Anderson, IBM. Chief Architect of the DITA Open Toolkit.

July 23: Managing Content and Producing Output with the Eclipse IDE
Presenter: Tom Ed White, Tekelec

June 25, 2008: The DITA Troubleshooting Specialization
Presenter: Carolyn Inkster, IBM

May 28, 2008: Brushing your teeth with DITA: Leveraging relationships to improve usability
Presenter: Shane Taylor, Computer Task Group

April 23, 2008: Using IBM Task Modeler to Create DITA-based Information Sets
Presenter: Kristen James Eberlein, Systems Documentation, Inc.

March 26, 2008: Round table discussion on DITA maps and relationship tables

February 27, 2008: Organizational meeting

January 23, 2008: Organizational meeting

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.

<insert your name and profile here>

Vendor representatives
<insert your name and profile here>

Consultants
<insert your name and profile here>

DITA Standards Development

History of DITA

The history of DITA is the history of its many powerful characteristics - modularity, structured writing, information typing, separation of content from presentation, single-sourcing, minimalism, topic-based, task-orientation, content reuse, conditional processing, localization-friendly, multi-channel, component publishing, usability, consistency, object-orientation, inheritance, specialization, simplified XML.

If you don't understand all these DITA characteristics, you may not have analyzed the DITA Business Case properly - for your organization, or for yourself if you are a professional writer.

You don't have to know how to do all these things to use DITA, but if there is no one in your organization who knows why you should use them, you may have a problem. If you have already been doing some of these things, you will want to know how DITA incorporates them.

Before 1960
The 1960's and '70's - Programmed Learning, STOP, QRC, Advance Organizers, Information Mapping
The 1980's - SGML, IBM Task Orientation, Desktop Publishing, Macintosh Documentation Guidelines, and Information Typing
The 1990's - Windows Help, IBM Minimalism, and XML
The 2000's - IBM DITA and the Open Toolkit
OASIS DITA

Before 1960

The historian of technical communications, R. John Brockmann, researched efforts to document products going back centuries. He finds that some of today's hottest new documentation ideas were present in the work of those creating, documenting, and selling the technology of manufacturing just after the revolutionary war.
( From Millwrights to Shipwrights to the Twenty-First Century: Explorations in a History of Technical Communication in the United States)

Today's computers, with their spectacular graphical interfaces, allow us to present animated visual images, even 3-D models to illustrate complex machinery. But this is not the work of the everyday tech writer. Flash animations and computer-aided design (CAD) demand skills more like those found in a game design team than a lone tech writer and wordsmith.

Brockmann found that two-dimensional images were a key part of 18th century technical documents. And modern ideas like modularity were there in the form of documents which were as often a set of cards as a book. He also found that early work was very user-centered and task oriented, and that it took advantage of knowledge already available to the user.

It seems that much of the change in today's technical documentation is the direct influence of the computer, and for some obvious reasons:

Software documentation, including online help, had become the paradigm for today's tech writers.
Since desktop publishing appeared, we rely heavily on the computer to assist us in the preparation of our documentation.
Theorists of computer documentation thought they were in a new field and simply reinvented practices long in use for explaining ordinary machines.

The 1960's and '70's - Programmed Learning, STOP, QRC, Advance Organizers, Information Mapping

At Harvard in the 1960's, computers were enlisted to become "teaching machines" by the behaviorist B.F.Skinner. His ideas of "programmed learning" still have influences in today's eLearning models. His work required knowledge to be broken down into chunks.

Hughes STOP - (Sequential Thematic Organization of Publications) advocated a storyboard approach with two-page spreads. A large graphic on one page, with clear labels, faces the main explanatory text on the opposite page.

The U.S. Navy published the Quick Reader Comprehension (QRC) method in 1961. It explicitly called for modular documentation that could be reassembled and reused for different purposes, perhaps the first mention of Reuse.

David Ausubel first proposed Advance Organizers in 1960. They are formal versions of the teacher telling the students what will be said (then saying it, then telling them what was said - a summary, in the classic three-step teaching method). Ausubel advocated images and clear titles and subtitles that revealed the structure in a document.

In the mid-'60's Robert Horn (winner of an ACM SIGDOC Lifetime Achievement Award for Documentation) developed Information Mapping techniques and founded the company by that name. Common "Information Types" were identified in dozens of standard document types like user manuals, policy and procedure manuals, annual reports, etc. Identifying standard information types is at the heart of DITA (Darwin Information Typing Architecture).

In the late '60's, Charles Goldfarb, Edward Mosher and Raymond Lorie (whose surname initials were used by Goldfarb to make up the acronym GML) created IBM's Generalized Markup Language for documents. In 1974, GML became SGML, with the help of Yuri Rubinsky and others. SGML was the standard for many years of structured documents in the military, aerospace, and large computer companies. It became the basis of DocBook.

In 1973, David Wooley at the University of Illinois developed PLATO Notes, a kind of message board. Posted topics were the basis of an online community supporting the PLATO timesharing system. Ray Ozzie used PLATO Notes as a student at Illinois and in the 1990's created Lotus Notes, including some features of PLATO notes.

The 1980's - SGML, IBM Task Orientation, Desktop Publishing, Macintosh Documentation Guidelines, and Online Help

In 1980, the ANSI standard committee for Information Processing published the first working draft of the SGML standard. SGML was the standard for many years of structured documents in the military, aerospace, and large computer companies. It became the basis of DocBook.

In 1981 a team at IBM led by Fred Bethke called for a new "task orientation" in computer software documentation. Their report, IBM Improving usability of publications (1981), contrasted documents that reflected the software systems architecture. They found that a user had to already understand the software to find the help they needed. Inexperienced users got lost. Another approach had been role-based documentation. But the new idea for Bethke was task orientation, which deals with the tasks people commonly perform with computer programs, regardless of their job titles, and focuses on the information needed to perform the tasks.

In 1981 Interleaf introduced technical publishing software for document authoring and composition. It included word processing, graphics, charts, tables, equations, image editing, and automatic page layout. Interleaf automatically generated indexes and tables of contents for books, and featured conditional processing of content.

In 1983 IBM's Santa Teresa Laboratory published Producing Quality Technical Information (now unavailable), guidelines for technical writing, mostly within IBM and mostly for software documentation. The team of writers included Fred Bethke, whose earlier IBM Publishing Guidelines has established the importance of task orientation. They identified seven quality characteristics as task orientation, organization, entry points, clarity, visual communication, accuracy, and completeness.

In 1984, the new Apple Macintosh was a revolution in computer user interfaces and a similar revolution in computer documentation. The user interface for documents was WYSIWYG (what you see is what you get - when you print the document). Affordable Desktop Publishing was born. The first DTP program, the $99 MacPublisher, was created by Bob Doyle, in the year of the Mac. Aldus (later Adobe) PageMaker followed in 1985. These tools led technical writers to style their documents and even arrange the content layout on the page. To this day DTP thinking is the most important inhibitor of content reuse, mixing presentation with content.

The new Macintosh Documentation Guidelines called for three sections. A Learning overview with tutorials that introduce new concepts and functions, an extensive Using section that spells out how to accomplish tasks, and a program Reference section. To this day, well written books on computers (for example those from O'Reilly) have Learning (e.g., Learning PHP), Using (e.g., Programming PHP), and Definitive Reference volumes.

Note how Learning, Using, and Reference map perfectly onto the three DITA information types specialized from the basic DITA Topic structure - Concept, Task, and Reference. And note that the Macintosh "Using" section was task-oriented, just as IBM was recommending.

In 1984 Lotus introduced their spreadsheet program 1-2-3, which was later the first software to use the F1 key to invoke context-sensitive topic-based online help.

In 1986 FrameMaker was introduced on the Sun OS. This DTP program was designed for long-form documents like books. It became very popular among professional tech writers and at $2500 was a major competitor for the much more expensive Interleaf system.

In 1987 Ralph Walden wrote Microsoft 's first online Help system, QuickHelp, for MS-DOS. He would later develop WinHelp and HTML Help.

In 1986 R. John Brockmann published Writing Better Computer User Documentation. Brockmann described the changes needed to move from paper docs to online. He reported on the new task-based approach, which limits information to that needed to perform a single task, assuming that the user can find general information elsewhere, or very likely already knows it.

In 1988 SoftQuad founder Yuri Rubinsky gave his high-school friend Peter Sharpe the task of developing Author/Editor for SGML, the first specialized SGML editing application.

In 1989 Bob Horn published Mapping Hypertext, an extraordinary book with fantastic illustrations - all drawn by Horn himself - exhibiting the kind of structured writing that Information Mapping was proposing for all documentation. This is still one of the most important books in the history of documentation in general (it's not about computer docs). The book described the seven information types of a structured document - classification, concept, principle, procedure, process, structure, and fact. Horn was inspired by Harvard Professor George Miller's famous work on the Magical Number Seven (plus or minus two) as the number of things easily learned at one time.

Learning theorist Dr. Ruth Clark would trimmed these down to five - concept, principle, procedure, process, and fact - her information types for Training and eLearning - in her workshops and book Developing Technical Training: A Structured Approach for Developing Classroom and Computer-based Instructional Materials. But Clark says the idea for these five types came from instructional theorist M.David Merrill and his "Content-Performance Matrix," not from Information Mapping.

The 1990's - IBM Minimalism, Windows Help, and XML

In 1990 MIT Press published the research results of another IBM team led by John M. Carroll. Carroll's book, The Nurnberg Funnel introduced the idea of minimalism in technical writing. It was task orientation carried to an extreme. Minimalism meant small non-linear chunks readable in any order. It emphasized reading To Do, not reading To Know or To Learn, a phrase first introduced by Ginny Reddish. It attacked the standard systems approach to learning of Gagne and Briggs, with its hierarchical decomposition of learning objectives, which remains to this day as a standard in learning systems. And it emphasized handling errors when the user could not accomplish a task.

Minimalism included the earlier IBM task-based approach, and it limited instructions to the bare minimum needed to perform a single task, assuming that the user can find general information elsewhere, or very likely already knows it.

William Horton published Designing and Writing Online Documentation: Help Files to Hypertext in 1990. It contains clear references to many of the most important concepts in technical writing - task orientation and topic-based content, single sourcing and reuse, and conditional processing, Horton called for new names for tech writers - "document weavers" and "topic writers." Horton's topics had topic sentences, smooth transitions, and summaries. These are difficult to accomplish when online topics are written to be read in any order, and there is no beginning, middle, and end (p.216).

Also in 1990 Microsoft introduced WinHelp 1.0, developed by Ralph Walden, Cheryl Zubak, and others.

In 1991 Ed Weiss produced a book - How To Write Usable User Documentation - on structured and modular documentation that was itself an excellent example of structured and modular documentation, following closely the STOP methodology developed in the 1960's.

In 1991 Sun Microsystems introduced FrameBuilder, a version of FrameMaker with added support for SGML.

In 1991 Arbortext released Adept, their SGML editor, later to be known as Epic, and finally simply the Arbortext editor, when Arbortext was acquired by PTC.

In 1992 Blue Sky software released RoboHelp, a task-oriented, topic-based, online Help Authoring Tool (HAT). Later they changed the company name to eHelp. eHelp was acquired by Macromedia, prinmarily to get the Flash-based tool RoboDemo (now Captivate). RoboHelp was discontinued, but after Macromedia was acquired by Adobe, RoboiHelp became a strong part of Adobe's Technical Communication Suite, including FrameMaker.

In 1992 at Lotus a team of user assistance specialists started to design a single "Working Together" common help design for Lotus' office package SmartSuite and Lotus Notes. John Hunt (1-2-3), Janet Smith (Freelance Graphics), Bryan Steh (Word Pro), and Susanna Doyle (Notes) created a core design with six topic types: overview, context-sensitive, steps, details, examples, glossary, and reference. It used Notes for content management and WordPro templates for editing, with single-source/multiple output to a variety of delivery formats.

In 1992 the HyTime standard for Hypermedia and Time-based content (an application of the SGML architecture) identified problems with linking document types that was to inform the specialization mechanism in DITA.

In 1994 JoAnn Hackos published her landmark Managing Your Documentation Projects, revised and republished as Information Development: Managing Your Documentation Projects, Portfolio, and People by Wiley in 2006. Fully in tune with task orientation, Hackos book described only three information types - concept, procedure, and reference (p.236). This seems to be a combination of Information Mapping's seven types, Ruth Clark's simplification to five types, and Apple Macintosh Documentation Guidelines three components.

In the mid '90's, Yuri Rubinsky's team at SoftQuad (creators of one of the first and most popular HTML editors, HoTMetaL, became involved in the development of a compromise markup language somewhere between the extraordinarily complex SGML and the popular new HTML (Hypertext Markup Language) for web pages. (HoTMetaL was the precursor to today's XMetaL from Justsystems.) HTML was a disaster from the point of structured reusable component documentation, not least because it combined presentation markup with structural markup. The new markup language was XML (eXtensible Markup Language), and SoftQuad developed one of the first XML editors, XMetaL.

In November 1995 John Carroll convened a workshop, sponsored by the Society of Technical Communication (STC), to evaluate Minimalism in the years since the Nurnberg Funnel. Carroll invited his major colleagues - R. John Brockmann, David Farkas, JoAnn Hackos, Hans van der Meij, Janice C. (Ginny) Reddish, and others.

In 1995 Adobe acquired FrameMaker and FrameBuilder, which was to become FrameMaker + SGML, and eventually the more affordable Structured FrameMaker, now included with every copy of FrameMaker, though used by a small percentage of tech writers. Most writers continue to prefer unstructured documents.

In 1995 CNET Founders Halsey Minor and Jonathan Rosenberg built their own Web content management system and it introduced a number of today's core capabilities, like content reuse and personalization. Page templates assembled the content dynamically from a relational database. They sold the system to Vignette for a share in that new company. It was the first "content management system (CMS)."

In Toronto in 1996, an IBM documentation team including Michael Priestley, Bob Fraser, Dennis Bockus, and Jamie Roberts was developing a Help system for IBM's new line of VisualAge software. Roberts had just returned from graduate study at University of Waterloo and attended a brainstorming session to define some basic information topic types for the new Help. He was inspired by Lotus' online help in 1-2-3, which then had the reputation of being very good at user experience. Lotus Help included procedures (called "steps") and overview (concept). Roberts scribbled "concept, task, and reference" on a napkin, handed it to Bockus for implementation, and a new help document architecture was born. There is not much unusual about a Help system that is task-based and assembled from topics. What was new was that this was to become the simplified form of XML known as DITA, with very significant contributions from Lotus, which IBM had just acquired. And it was to be both web-based and delivered as a PDF.

After the release of Windows 95 and WinHelp 4, in 1996 Scott Boggan, David Farkas, and Joe Welinske wrote Developing Online Help for Windows 95. It had a strong task orientation and was topic-based. But "concept/overview" was only one of ten standard topics, which did not include "reference," but did wisely include errors and troubleshooting.

In 1996, IBM signed a long-term agreement to use the Arbortext Adept editor for internal SGML document creation.

In 1997 Microsoft released Compressed HTML Help (.CHM), based on compiled HTML, images, and Javascript.

In 1998, JoAnn Hackos and Ginny Reddish published the definitive reference on task analysis, User and Task Analysis for Interface Design, and John Carroll published the edited proceedings of his 1995 workshop, Minimalism Beyond the Nurnberg Funnel, with major contributions by Hackos and Reddish.

In 1998, IBM revised their 1980's PQTI tech writing guide, retitling it Developing Quality Technical Information. The team of writers was led by Gretchen Hargis and included only one from the PQTI team, Polly Hughes. They now cited nine quality characteristics - accuracy, clarity, completeness, concreteness, organization, retrievability, style, task orientation, and visual effectiveness. Note that task orientation had slipped from first to eight out of nine quality characteristics.

The 2000's - IBM DITA

In March 2001, IBM introduced DITA as a series of developerWorks articles about a new simplified version of XML for documentation. It was intended to replace IBM's IBM ID Doc, an internal version of SGML for IBM's technical software support. While XML was enjoying great use as a data exchange method (RSS and SOAP protocols), it had little traction as a document markup language. DITA was an attempt to make a simplified XML starter set for documentation markup, one designed from the outset to encourage reuse of small content components. The key ideas were to be simpler than the complex SGML and also be usable online.

The goal of DITA was to formalize information typing practices, both print and online, and also enable an extensible typing architecture through specialization of base topics. DITA maps were a way to standardize collection publishing and information architecture/outlining models. DITA was initially known as MITA, for Mendel Information Typing Architecture, to emphasize the object orientation of the new architecture, with its "inheritance" and evolution of topic structures via specialization. Since MITA was already a somewhat proprietary acronym, IBM switched to Darwin and DITA.

In May 2002, IBM added domain specialization to topic specialization, and demonstrated these in the Open Toolkit, a reference implementation of DITA publishing, with a starter set of XSLT stylesheets. IBM encouraged authoring tool vendors to integrate the Open Toolkit as a means of publishing DITA, and most have done so.

JoAnn Hackos' Content Management for Dynamic Web Delivery was published in 2002. She described creating an information (content) model and developing information types, such as procedures, concepts, warnings, specifications, and others. Michael Priestley, the DITA specialization architect, and Dave Schell, then the principal DITA evangelist for IBM, wrote a 3-page vignette on DITA, perhaps its first mention in a book. They stressed topic orientation, information typing, specialization, inheritance, and two architectures, one for information and one for specialization. Hackos briefly mentions the AutoCAD Learning Assistance software she and learning guru Wayne Hodgins developed for Autodesk. It was cleverly dubbed CPR for its three-tabbed interface to concept, procedure, and reference.

In 2003, two books appeared on single sourcing and content reuse, Single sourcing: Building Modular Documentation, by Kurt Ament, and Managing Enterprise Content, by Ann Rockley.

In 2003, IBM published a second edition of Developing Quality Technical Information, by Gretchen Hargis and others. Now the nine quality characteristics were rearranged once more, putting task orientation first again. More importantly, they added an introductory chapter that called for content to be structured as separate information types, specifically task, concept, and reference. (Note the correct order of the three basic DITA information types.) This book is all about DITA without mentioning the name, probably because IBM was using DITA internally but not yet sharing it with the world when the book was drafted.

OASIS DITA

In April 2004, the Organization for the Advancement of Structured Information Standards (OASIS), formed a Technical Committee to explore a DITA Standard. The TC included XML tools vendors, consultants on Information Architecture and Content Management Systems (CMS), and end users of the DITA Document Type Definitions (DTD) and Schemas needed for the new DITA Standard.

In February 2005, IBM donated the Open Toolkit, a limited version of their internal Information Developers Workbench, to SourceForge. IBM continues to develop the OT, which is not a part of the OASIS DITA Standard efforts.

DITA 1.0

DITA 1.0 was approved as an OASIS Standard in June 2005

DITA 1.1

DITA 1.1 was approved in August 2007, adding a new Bookmap specialization.

DITA 1.2

DITA 1.2 is expected sometime in 2008. It will add structured learning, creation of Learning Objects with DITA, which will be compatible with eLearning standards such as SCORM.

References

From Millwrights to Shipwrights to the Twenty-First Century: Explorations in a History of Technical Communication in the United States , by R. John Brockmann.

History of Outlining (and STOP).

Quick Reader Comprehension (1961).

Hughes STOP - Sequential Thematic Organization of Publications (1965).

IBM Improving usability of publications (1981). Task-orientation HTML version

Writing Better Computer User Documentation (1986)

Mapping Hypertext, Robert Horn, Lexington Institute (1989).

Developing Technical Training: A Structured Approach for Developing Classroom and Computer-based Instructional Materials, Dr. Ruth Clark (1989, 2nd edition, 1999).

Designing and Writing Online Documentation: Help Files to Hypertext, by William Horton (1990).

The Nurnberg Funnel, John M. Carroll, MIT Press(1990).

How To Write Usable User Documentation, by Edmond Weiss, Oryx, (1991)

Managing Your Documentation Projects, by JoAnn Hackos (Wiley, 1994).

Developing Online Help for Windows 95, by Scott Boggan, David Farkas, and Joe Welinske, (Solutions, 1996).

Standards for Online Communication, by JoAnn Hackos (Wiley, 1997).

Robert Horn, Visual Language (1998).

User and Task Analysis for Interface Design, by JoAnn Hackos and Janice C. (Ginny) Reddish (1998).

Minimalism Beyond the Nurnberg Funnel, John Carroll, MIT Press(1998).

Two approaches to modularity (1999). Robert Horn compares structured writing to Hughes STOP.

Review of the Nurnberg Funnel (1999) Robert Horn compares structured writing to Minimalism.

The Impact of Single Sourcing and Technology, Ann Rockley, 2001.

Cisco/Clark Reusable Learning Objects.

Content Management for Dynamic Web Delivery, by JoAnn Hackos (Wiley 2002).

Managing Enterprise Content, by Ann Rockley, New Riders, 2003.

Single sourcing: Building Modular Documentation, by Kurt Ament, Andrew Publishing, 2003.

Robert Horn Powerpoint on Visual Language.(2003).

Developing Quality Technical Information: A Handbook for Writers and Editors (2nd Edition) , by Gretchen Hargis, Michelle Carey, Ann Kilty Hernandez, Polly Hughes, Deirdre Longo, Shannon Rouiller, Elizabeth Wilde (IBM Press, Information Management Series, 2004).

Information Development: Managing Your Documentation Projects, Portfolio, and People, by JoAnn Hackos (Wiley, 2006).

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 op

DITA Wiki Knowledgebase

See also:

Setting up DITA

Getting started

See also:

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

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

See also:

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 organizations using DITA

DITA user groups

Regional DITA user groups

Virtual DITA user groups

Potential new DITA user groups

See also:

Research Triangle Park (RTP, NC) DITA users' group

Charter

Meetings

Communications

Upcoming events

Past events

List of speakers for DITA presentations

DITA Standards Development

History of DITA

Before 1960

The 1960's and '70's - Programmed Learning, STOP, QRC, Advance Organizers, Information Mapping

The 1980's - SGML, IBM Task Orientation, Desktop Publishing, Macintosh Documentation Guidelines, and Online Help

The 1990's - IBM Minimalism, Windows Help, and XML

The 2000's - IBM DITA

OASIS DITA

DITA 1.0

DITA 1.1

DITA 1.2

References

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