Select Page

DITA XML is a form of structured content that is optimized to create, reuse, translate, and publish documentation quickly by using topics and maps. DITA XML is also a community maintained open standard.

There’s a lot of unpack from that definition, so we’re going to dissect it into a series of smaller questions:

If you feel like you already have a good conceptual grasp of DITA, read about what it can actually do for you!

 

 

 

 

First, let’s start from the top. DITA XML is a form of structured content, which begs the question:

What Is Structured Content?

We’re all familiar with content. Content is everywhere. It’s everything you read, listen to, watch, etc. Content is how we communicate ideas to one another.

Content is communicated through various mediums to take ideas in our minds and transmit them to other people. For most of human history, we would do this by speaking to one another. Today, we use images, videos, written words, podcasts, VR, AR, voice assistants, and more. Ultimately though, the goal is the same; to get an idea from one person’s mind into another.

Structured content is content that follows the rules of a standard (we’ll talk more about standards in a moment). These rules establish a consistent framework that enables applications and systems to interact with content in helpful ways. In other words, these rules allow the technologies we use to communicate our ideas to understand us better. Because human words are messy to machines.

These rules give systems and applications a guide for how to interpret and leverage content. Typically, structured content uses tags to identify types of content. The most popular example of this is HTML. HTML uses tags to tell systems how to display our content in our internet browser.

The reason these systems need rules and tags is because our human language is nuanced and complex. Different people, in different contexts, use different words, in different ways.

These tags communicate how the system should interpret the messy-human-words. For example, you can think of these tags like facial expressions when talking to other people. The same word or phrase should be interpreted differently based on the facial expression that accompanies it.

If you ask a partner how they’re feeling and they respond:

“I’m fine 😊,” with a smile and bright eyes, that’s good.

“I’m fine 😔,” with a wistful sigh and a downward glance, you know they’re masking some discontent.

And if they say, “I’m fine 😠,” with a glare and a frown, you should probably apologize for whatever you did and back away… Slowly.

This is incredibly important and if you walk away from this post having only learned one thing, let it be this:

Structured Content beats unstructured every single time.

Ok, let’s recap. Structured content is content that follows rules of a standard. These rules provide a consistent way for systems and applications to interpret our messy-human-words with the aid of tags. Unstructured content, like typical document or text editors, lack these tags and rules.

Where do these “rules” of a standard come from?

Let’s talk about open standards.

What Is a Standard?

A standard is the collection of rules of the structured content language. The rules are crucial. If you play baseball, you have rules. These rules are important because they tell you how to play the game.

3 strikes: you’re out.

However, what if you play another team and they have different rules?

5 strikes: you’re out. This is a problem.

The standard ensures that everyone is utilizing the structure in the same way just like a rule book ensures that all the teams within a league follow the same rules. This consistency is crucial. For a system or an application to interact with your content, not only do you need structure, but you need to use the same structure that the system is programmed to interpret. The content creator and the content interpreter need to use the same structure. Thus, the standard ensures that everyone is using the same structure in the same way.

What Is an Open Standard?

A standard is a rule book, but what makes a standard an open standard?

Simply put, an open standard is one that is not proprietary. No one person or company owns it.

In other words, the standard is not limited to or dictated by the whims of a company.

If we (easyDITA) disappeared tomorrow, DITA XML content would still have the same value. Granted, it would be less fun to create, manage, and publish (sorry not sorry), DITA XML content would retain its value because it is part of the open standard of DITA. It’s not dependent on easyDITA or any other vendor.

If DITA isn’t controlled by a company… What happens when the standard needs to update?

When Standards Change

Ready for today’s vocabulary word?

Högertrafikomläggningen.

While it looks like the transcription of a viking’s sneeze attack, In swedish, this translates to “The right-hand traffic diversion” and it describes September 3rd of 1967. A unique and hilarious day in history.

On that date, in Sweden, all traffic was diverted from the left side to the right side of the road. Stop and think about that. If you spent your whole life driving on one side of the road, only to switch overnight. Suddenly, the daily commute is no longer automatic, yielding right of way takes more thought, and one way streets become a nightmare.

On the day of the switch, at 4:50 am, everyone on the road had to stop their vehicle and move to the opposite side.

What was the result? You might expect it was anarchy, and to a degree, it was. There were many fender benders and traffic jams, and a handful of serious accidents, but for the most part, traffic accidents actually went down after the change as people quickly adopted the new rules.

But what does this have to do with DITA? The laws of the road are a type of standard. They establish shared expectations of behavior so that the whole system works as it should. But, sometimes those rules need to change. Sweden’s neighbors drove on the right side of the road, additionally, most swedish vehicles had steering wheels on the left side of the vehicle. The change, while difficult, was necessary in the long term.

It’s the same with the DITA standard.

The DITA open standard is maintained by the OASIS DITA Technical Committee. All changes and updates are handled methodically and intentionally for the good of the writing community as a whole, not any single vendor’s bottom line.

Sometimes a change is necessary, but it’s also necessary that the code be consistent, predictable, transparent, and publically available. Too many changes too quickly would be disastrous.

Since its formation in 2004, the committee has made only a handful of updates to the standard, aimed at maintaining continuity, improving quality, and avoiding disruption.

That’s enough about standards, as long as you remember that the long term stability of the structured content language is highly dependent on the kind of standard to which it adheres.

The DITA standard has been around longer than most and has proven itself in consistency and reliability.

Ok, now we’re going one step further towards DITA in practice. Topics.

What Are DITA Topics?

DITA arranges content as components. Components are super cool, self-contained, building blocks of content. They’re like building blocks that you use to construct publishable documents. You can rearrange, re-use, and easily update components. We wrote a whole, separate explainer about components and component content management systems here.

Topics are the most common form of components found in DITA and they are important because they represent a completely different way of thinking about and creating content.

A typical document is written in a linear manner, meaning that it is full of ideas that are intertwined and interdependent. The ideas are good, but they are impossible to isolate.

However, when you write your content in the form of topics, you are writing each idea within its own, pre-isolated, container. Once your topics are written, you can then arrange them, but they never become messily interconnected.

There are a few standard topic types:

  • Concept
  • Task
  • Reference
  • Glossary

There are others, but these four make up the vast majority of usage.

Concept topics are incredibly versatile. You will often see them used to talk about something. Concept topics can be used for product descriptions, subject introductions, extended definitions, and the like.

 

Task topics are the “How to” topics. They are perfect for step-by-step instructions.

Reference topics provide specifications about the subject. Usually, this information is represented in a bulleted list or a table. The reference topic is the place to go if you have questions about specific referential things like product part numbers, environmental specifications, API info, etc.

Glossary topics define terms. Glossary topics are essential to maintaining consistent language throughout our content. Each glossary topic is limited to a single definition of a term. If a single term has multiple definitions, each one gets its own topic. This is super important when communicating with other people.

All these types of topics are a terrific method of capturing ideas into succinct components of content.

If you’re not sure about when to use each topic type, we wrote an explainer here.

You’ve written your DITA topics, but how do you arrange them?

This is where DITA Maps come into play.

What Is a DITA Map?

DITA maps are larger containers to our topics. Topics are the content, but maps are absolutely crucial to getting the most out of our topics.

You can think of a map as a… well… a map.

For those of you who don’t remember, a map was the analog method of navigating unfamiliar terrain. Whether you were on a road trip, or hiking through the wilderness, a good map was invaluable in getting from point A to point B.

While the modern smartphone equipped with google maps provides the same function, there’s something uniquely empowering about pulling out a well-worn map, with its weathered corners and worn creases, and viewing the upcoming journey in its entirety. Maps provide direction, distance, the order of the landmarks, and the surrounding terrain.

A map gives purpose and order to a series of landmarks.

In the same way, a DITA map gives purpose and order to a collection of topics,

A DITA Map provides:

  • Order and hierarchy
  • Navigation (like a table of contents)
  • And Cross-topic links in the final deliverable

A good map guides the traveler from point A to point B and provides all the relevant information, in the correct sequence, between those points.

In the same way that a road map was essential to a successful road trip, a DITA map is essential to a helpful, published document.

Why Should I Use DITA XML?

We’ve talked about what DITA is, but now it’s time to shift the conversation to you and your organization. Why should you consider DITA XML as a content solution? The easy route is to talk about benefits, but ultimately, that’s not enough. Features and benefits are cool, but can be nebulous and abstract. We want to get concrete and talk about capabilities. We want to talk about what DITA XML can do.

If you think you understand the concept of DITA (and hopefully you do after reading this piece) you’re ready to look at the capabilities of DITA in action.

  • We highlight a number of capabilities in this post:
  • Turning your content into components
  • Reusing your content anywhere, quickly
  • Leveraging metadata so you can actually find your content
  • Publishing everywhere, simultaneously, with no manual formatting needed

Read more

DITA, when stored in a Component Content Management System (CCMS), can become your single source of truth. No duplicates, no pasted items, just a centralized repository of knowledge that your organization can trust to be consistent – everything in its place.

Now that you understand what DITA is, it’s time to do something with that knowledge.

How to Get Started with DITA XML?

DITA XML is powerful, but it’s also accessible. Gone are the days when you needed to write full XML code into an editor. Systems like easyDITA provide familiar, intuitive content experiences without limiting the potential of the DITA content. If you’re ready to get your hands dirty and start building DITA content, you can give easyDITA a test drive.

Tools like our Microsoft Word-to-DITA converter make it easy for you to start experimenting with your existing content.

If you want to learn DITA XML from the beginning, we’d recommend going through the LearningDITA coursework at LearningDITA.com. We helped to write some of the curriculum and it provides a terrific education on all the nuts and bolts.

If you just want to read some more, here are some of our top articles about DITA XML!

Got questions? We’re always here to help! You can schedule a free consultation with one of our content experts here.

John Baker
Get a Demo
X