Supported output formats

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

• PDF, through XSL-FO
• XHTML
• Microsoft Compressed HTML Help
• Eclipse Help
• Java Help
• Rich Text Format

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

See Portuguese translation of this page.

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

• Boston DITA User Group
• Boulder-Denver DITA User Group
• Central Texas DITA User Group
• Indy DITA Users Group
• Los Angeles DITA Interest Group
• Melbourne (Australia) DITA User Group
• New York DITA Users Group
• Research Triangle Park (RTP, NC) DITA User Group
• Silicon Valley DITA Interest Group
• Toronto DITA User Group
• UK DITA User Group
• Vancouver DITA User Group
• South African DITA User Group
• Portland, OR User Group

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
• dita2go on Yahoo Groups
• Facebook DITA group
• FrameMaker-DITA on Yahoo Groups
• dita-fmx-users on Yahoo Groups
• Second Life: Addicted to Reality 13, 27, 24
• X-Metal DITA Yahoo Group
• Dutch DITA users on LinkedIn
• DITA machine industry on LinkedIn

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.

See also:

• Host your user group on DITA XML.org
• Services for DITA user groups
• Potential new DITA user groups (archive 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 in 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)

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.

See also:

• DITA Architectural Specification description of specialization
• An XML-based information architecture for learning content, Part 1: A DITA specialization design (IBM)
• Specializing topic types in DITA (IBM)
• DITA Configuration and Specialization Tutorials (Kimber)
• Specializing domains in DITA (IBM)

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
  • DITA 1.0 - Task, Concept, Reference, Specialization
  • DITA 1.1 - Bookmap
  • DITA 1.2 - eLearning

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, Laura Rintjema, 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 December 1999, IBM formed an internal workgroup to develop an XML content architecture to replace their existing book-oriented SGML content architecture, called IBMIDDoc. The workgroup was led by Don Day, with a subworkgroup focused on developing the prototype DTDs led by Michael Priestley. The DTDs encoded the existing IBM content typing architecture (concept, task, and reference topic types) and related them to a common base type, the generic topic, through a new process called specialization.

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. 

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 was released in 2010. It added structured learning, creation of Learning Objects with DITA, which will be compatible with eLearning standards such as SCORM.

DITA 1.3

DITA 1.3 is expected for final release in 2015. It will add the new troubleshooting topic, release management, scoped keys, and other additions requested by the burgeoning user community. 

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

See Portuguese translation of this page.

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, reference, troubleshooting, and glossary. 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.

dita-users Yahoo Group

This mailing list to support DITA was set up as a Yahoo Group by IBM in May 2004 and called the IBM DITA Forum.

Main page: https://groups.yahoo.com/group/dita-users/
Post a message: dita-users@yahoogroups.com
Subscribe: dita-users-subscribe@yahoogroups.com

It now has over 4000 members and is the main mailing list for the DITA community.

Links to several other DITA-related mailing lists can be found here. 

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:

• 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.
• Introduction to the Darwin Information Typing Architecture - IBM developerWorks, Sept. 2005. The Darwin Information Typing Architecture (DITA) is an XML-based, end-to-end architecture for authoring, producing, and delivering technical information.

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 user wants to know the steps of a task, they can skip background information 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.

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

See Portuguese translation of this page.