Level One: Topics

Introduction to DITA Maturity Model
Level 1: Topics
Level 2: Scaleable reuse
Level 3: Specialization and customization
Level 4: Automation and Integration
Level 5: Semantics on demand
Level 6: Universal semantic infosystem

At its most basic level, DITA is an
XML document markup language; but even
at its simplest level, DITA enforces a
topic structure and reuse architecture
that allows DITA documents to reuse content
from other, more structured projects.
This standardization also sets the stage
for topic-level reuse by others as an
initial migration of document-oriented content evolves to incorporate better management and authoring practices around topics and maps.


An author for a government agency may need to produce audience-specific versions of a government policy. The author can write all the content in one file and apply conditional processing values to produce different versions of the policy for permanent and contract employees.


The minimum DITA adoption requires that you migrate the current sources of content in XML. You do, however, have the flexibility to decide which sources to migrate when, and how much structure to apply to the migrated content. Many teams have a large amount of legacy information that was authored in a variety of sources. Some teams may choose to migrate only the content that will require updates in the future. Other teams migrate everything, but do not move the content into typed topics; instead they move the content en masse into generic topics, which are the least restrictive topic type and hence require the least amount of content restructuring. However, the generic topic type also provides the least amount of semantic value.

Figure 2

Figure 2. Topics

Another way that teams save time at this level is to defer splitting the content into discrete topics and simply recreate their existing document-focused structure by nesting multiple topics within a single file. For example, recreating chapters
as DITA files allows you to continue to store all the chapter content in a single file. While this strategy takes less time than restructuring the content into units based on subject, it does not provide small enough units of information to enable
easy reorganization of the content into multiple deliverables.

Because XML separates the formatting from the content, the transform for each deliverable type applies the styles and formatting defined in the cascading style sheets (CSS) when you generate or publish the deliverable. Although the DITA
Open Toolkit provides default processing for multiple deliverable types, you must customize the transforms to generate deliverables that meet the style, standard, and branding requirements for your organization.


Even with minimal investment, you can realize returns from adopting DITA. Many teams make the move to DITA to gain greater reuse of their content. Working with their current source, they use conditional processing to generate multiple versions of the same document. Even with non-typed topics or multiple topics in the same file, you can
easily specify conditions and generate conditional output with DITA. This remains the primary means for reusing content at the first level of adoption.

However, to make progress toward the goal of additional reuse, you can use DITA to meet the challenge of publishing new or multiple deliverables that contain the same information by single-sourcing the content. The DITA Open Toolkit provides default output processing for a wide variety of popular formats, including HTML files, Eclipse3
plug-ins, PDFs, and CHM (Microsoft® Compiled HTML Help) files. You can easily generate the same information in multiple formats by specifying a different output type when you publish.

When you publish content, the publishing transform applies the specified formatting to each element, which allows you to easily update format styles for large quantities of information. For example, if the style for highlighting the first instance of a term is italics, but later is changed to bold, you simply update the CSS and regenerate the
deliverables. This is much more effi cient than searching for and updating each instance of a term or style element across the information set.

For links between content, most teams use hard-coded cross-references in their current source. At the basic DITA adoption level, you can continue this practice and link between DITA topics, as well as to external documents or locations, such as Web sites.

Lastly, at this level, most teams utilize minimal or unmanaged metadata and primarily focus on terms, such as index terms.

By migrating the content source to XML and chunking it according to the appropriate topic type, the first level of adoption supports conditionally generating output and positions you for greater reuse and output flexibility at the next level.

DITA features used

This adoption level uses the following DITA features:

Nested DITA topics

DITA provides the ability to nest topics hierarchically within a single XML file. You can chunk the content by topic type, but you don’t have to create separate fi les.

Cross-reference elements

You can create cross-references to elements, such as linking to other topics, to non-DITA files, to Web pages or to specific sections referenced from within a bulleted list. These references are hard-coded into the content, which may have implications when you reuse the content.

Conditional processing

You must define the processing attribute and its valid values in the .ditaval fi le in order to conditionally process content. By default, DITA provides three processing values, but you can create additional values by specializing the props attribute.

See also:

- Downloadable PDF of DITA Maturity Model
- DITA Maturity Model Q&A with Michael Priestley and Amber Swope

Log in and use the "Add new comment" link at the bottom of this page to share constructive criticism, make suggestions for improvement, and provide use case scenarios that can help enhance the DITA Maturity Model.

These are all great comments and should help others who are challenged with implementing DITA.

Thanks for sharing.

Scott Abel
Content Management Strategist
The Content Wrangler
blog: http://www.thecontentwrangler.com
community: http://thecontentwrangler.ning.com

Documentation and Training East 2008


"When you publish content, the publishing transform applies the specified formatting to each element, which allows you to easily update format styles for large quantities of information. For example, if the style for highlighting the first instance of a term is italics, but later is changed to bold, you simply update the CSS and regenerate the deliverables. This is much more efficient than searching for and updating each instance of a term or style element across the information set."


While this statement is true, I think it is a bit misleading. Coupled with the para preceding it, this text makes it seem like updating ALL formats is as easy as updating a CSS. That is not the case, at least not for PDFs. If you combine the lack of documentation for the OT with XMetaL's particular customization of the OT FO styles, it can be a rather trying task to figure out what is defined where, and further where each of those definitions is overwritten.

Now, I'm fairly new to DITA and XML, though I have some HTML experience (thankfully!), so I have an idea of how markup languages work. But let's take a simple example of a customization that might be common: adding a corporate graphic to the title page of a bookmap. In order to do so, I had to:

<ol><li>Read up on how XSL:FO works. I think a lot of people may stop here.</li>

<li>Figure out where the DITA OT defines page masters</li>

<li>Figure out where XMetaL overwrites the page masters</li>

<li>Define a before-region in the correct layout master</li>

<li>Learn enough XPath in order to...</li>

<li>Add an xsl:template to XMetaL's layout masters override in the correct sequence</li>

<li>Figure out the correct place to put the image, then point to it in the attribute set for the xsl: template...</li>


I may have missed a step, or gotten something out of order, but I think it's pretty clear that the process is not easy. Want to change the fonts that appear in your books to match corporate guidelines? You'll need to make changes in three different files!

At any rate, I think new DITA users--those most interested in Level 1 of the MM--are going to quickly find that updating styles for multiple outputs requires quite a bit of expertise.

I am a Project Manager of technology products at a major US publisher. Since I work in technology I can clearly see the benefits to moving technical documents and user guides to DITA and I can even see a company wide move in this direction for many of the publications. And since my major projects are all bilingual or in Spanish, I see that DITA dovetails nicely with OASIS XLIFF standards.

I'm creating the argument for the move to DITA on a very small scale (user guides, and design specifications to prove the efficacy of DITA). But much of what I have read here and elsewhere is focused on why to move not how to make the move.

I have found the DITA users tutorial site (listed below), but I wanted to see if there is something that could serve as a beginning guide for transition or best practices in this area. Since I am the only DITA advocate within my company any user success stories and pitfalls, or lessons learned documents would be helpful.

For example I recognize the basic concepts of structured authoring and topics but I'd like to have a bit more detail on pitfalls to avoid as I begin to create them. I am currently using oXygen to recreate a few user's manuals and illustrate the flexibility that DITA maps could provide to our documentation development. I'm sure I am just scratching the surface and anything that could help me to illustrate the potential would aid in the move to DITA.

All of our products have standard EULAs and flexible licensing, and many share basic interfaces. So in creating my topics would it be best to divide them up so that I can utilize maps?

I know these are very rudimentary questions, but I figured if anyone could help make sense of this it would be the groups most vested in its success.

Thank you in advance for your help and I apologize for these rudimentary questions.


Ah, where to begin?

I work for a software company writing techincal training. We've just started a DITA proof of concept project. While I can't tell you all the pitfalls to avoid as you start, I can share a major win we experienced...

To get our project kicked off, our project team sat in a room for 2.5 days and converted, as a group, an entire course into DITA. We started with a single topic projected on the screen and went through typing each bit of content on the page as a group. As we went, we discussed when to use various tags, which we would not use, and opportunities to specialize. Once we were all comfortable with the elements and ground rules, we split up the remainder of the course and converted it. At the end of the 2.5 days we had the equivalent of 350 pages converted to DITA, and far more practical experience built up on our team.

After that workshop, myself and another developer have been updating the content for a new product release, and finding that much of the content is still in BIG chunks that need breaking down. But that's ok; we're still learning. The real win is that we now have a core team of developers sharing their experience with others--the good and bad--which has led to a broader understanding of why and how we'll support single sourcing.

So I guess my advice is to get others involved as early as possible. (It sounded from the post that you were converting all the content yourself.) We've found that the technology is easy to learn and adopt--its the change managmenet that is the real hurdle.

"You do, however, have the flexibility to decide (...) how much structure to apply to the migrated content."

Correct! My advice to novice DITA users is: get to know the main DITA elements and attributes. I also make a distinction between what I call "DITA light" and "full DITA". For example: you can just wrap the steps of a task in <step> and <cmd> elements and don't worry about <uicontrol> and <wintitle> yet, which is "DITA light". Later, you can add more structure and semantics and use elements like <uicontrol> and <wintitle>.



Yves Barbion

XML.org Focus Areas: BPEL | DITA | ebXML | IDtrust | OpenDocument | SAML | UBL | UDDI
OASIS sites: OASIS | Cover Pages | XML.org | AMQP | CGM Open | eGov | Emergency | IDtrust | LegalXML | Open CSA | OSLC | WS-I