What is DITA XML? || [Beginners guide]
You are a technical writer working for an XYZ company and you daily come across the term DITA. Maybe you are well versed and know DITA from the crux or maybe you are preparing for an interview to understand, what is DITA all about? Why is everybody asking for it?
Table of Contents
You have browsed every article and still, things are superficial in your mind because of so many complex terminologies.
If there is one article you could read to comprehend easily, read this.
This article is easy to understand and written in profound detail.
In this article, I have discussed all the things that you are supposed to know about DITA for your own personal goal related to technical writing. Be it, cracking an interview, or becoming more efficient in your current job.
What is DITA XML?
DITA is an abbreviation for Darwin Information Typing Architecture (DITA). XML is the language in which the content/documentation is written.
DITA is an open-source standard that defines an XML architecture for designing, authoring, publishing, and managing content which is defined and maintained by the Organization for the Advancement of Structured Information Standards (OASIS).
DITA is followed as a standard for creating and managing documentation in most of the organization.
How is DITA followed into the Technical Writing process?
DITA helps the technical writer to write the XML content in a particular fashion which is called content modularization.
Now, what is content modularization? By this term, it is meant that the content is modularized or in simple terms broken into simple chunks of information.
Why would you do that? Simply, because it will be easier to find a specific chunk of information and it has a potential for reuse.
Let’s understand with an example.
Suppose you have all the information for writing a user manual for “Making of tea”.
You could either write it as a continuous paragraph listing all the tools required and with listed steps of instructions. This would look like a complete page with an essay.
Or you could break the chunks of information (as we say in DITA - modularize) and create separate topics for each section.
You can create:
Description topic - for explaining or describing the need for performing this job
Reference topic - for listing all the tools required.
Procedure topic - for giving the actual instruction for the job.
See the example image below which shows the grab from the DITA map manager from Oxygen tool. The grab shows how the individual topics (.xml files) are mapped under the bookmap (.ditamap file).
The magic happens when you break information.
Now, when you want to use the reference topic for another user manual (for example “Making of coffee”) which will require the same set of tools, you could actually reuse the written content instead of writing a new topic again.
The process of creating the XML files as a concept, task, and reference topics through an XML authoring tool (Oxygen, FrameMaker) is called structured authoring or topic-based authoring.
These individual XML files are then mapped under a ditamap. Then the ditamap is published into a chosen multiple outputs such as PDF, HTML, WebHelp, etc.
DITA summary and Topics
DITA is summarized as follows:
Darwin: uses the principles of specialization and inheritance.
Information Typing: emphasizes about the pieces of information present as topics.
Architecture: emphasizes the customization that can be done.
The latest version of DITA 1.3 has 5 topics as follows:
Concept
Task
Reference
Troubleshooting and,
Glossary
DITA bookmap Vs DITA topic
You should understand that the bookmap is a container map that contains all the mapping of the individual DITA topics (concept, task reference, glossary, troubleshooting).
Let’s understand through an analogous example, consider a paperback book (physical book such as a novel), the individual chapters present inside are the DITA topics and the whole book is the DITA bookmap. The physical book has some pages such as a preface, a bibliography that can be considered as the metadata.
Consider the following table for comparison.
How to create and publish content in DITA
DITA contents are the XML files. You can create these XML files in a basic text editor such as Notepad or Notepad++. You can also use an XML editor tool such as Oxygen, XMetaL to create the contents easily.
Generally, a technical writer uses the XML editors for creating and managing the contents because the XML editors take care of the XML syntax and schema. The editor also allows the drag and drop functionality of tags which enables the writer to nest taggings with ease.
The DITA contents created, or basically, the XML files can be transformed into the desired output with the DITA Open Toolkit (DITA-OT) plugin. DITA-OT is open-source. The DITA architects can configure it in the XML editor tool which allows transforming the XML contents into multiple output formats such as .pdf, .html, etc.
When DITA is configured into a CMS, contents can be published using the CMS after you have written content in an XML editor.
Why should you use DITA?
DITA is used as a global standard for the creation of documentation. Consider the following reasons why you or your organization should follow it:
Content reuse
When we create the document as fragments which are called topics, it can be easily reused in multiple places. Refer to the example discussed section “How is DITA followed into the technical writing process” for a detailed explanation.
Thus breaking the content into chunks increases the applicability as well as usability of the individual pieces manifold.
There are now many DITA-supported Content Management Systems (CMS) available in the market. When this CMS is integrated with the authoring tool, it helps the author in maintaining a warehouse of topics.
The author can determine the applicability of the respective topic and use it wisely by pulling under a required DITAMAP. This saves time and increases work efficiency.
Efficient and time-saving
Consider a single topic that is reused in multiple documents. Now if there is a change in that topic, we can simply make the necessary amendments, and the same changes get synced automatically in all the other documents.
This helps in saving a lot of time as it rescues you from manually making the same changes in all the documents.
However, you should also understand that if the new incoming changes are not applicable to some of the documents then you need to create a different topic to address the new changes. You have to make sure that the new changes are applicable in all the documents/places.
Search indexing
Search indexing is a DITA-based CMS feature. It is a process of retrieving the required set of data by filtering it from the lot.
For example, you have a database that contains 1000 topics for software documentation. You can search with a keyword and if all the topics relevant to that keyword will be shown as search hits to you. It thus helps in filtering out the data.
Topic-based authoring
Since most readers don't read information end-to-end. Thus a good information design needs to make sure each unit of information can be read on its own to give just-in-time help.
This is where topic-based authoring comes into the picture. A technical writer creates stand-alone topics that answer very specific questions on “how to” or “what is” or “where is”. When a search query is entered, these individual topics are shown as search results that are further consumed to solve a particular user query.
DITA supports this topic-based authoring architecture and also helps in creating a map out of these individual topics in a relevant sequence.
Highly customizable
DITA is highly customizable. A DITA architecture can customize DITA to custom requirements as per the client or organization standards.
The DITA architect usually sets up the writing environment for the writers. So, the writer can mainly focus on the quality content part instead of worrying about the background configurations and preferences.
Effective use of metadata
The bookmap which is a .dtamap file contains all the mapped topics under it. This bookmap can also contain numerous metadata such as author name, publishing date, the version number of the document, etc.
DITA helps in managing the metadata very efficiently. This metadata helps to define how the topics and bookmap should be styled, will there be any conditional processing using the .ditaval file or not, etc.
Quiz
Conclusion
DITA is the widely used standard used for creating documentation. DITA defines the relationship between the individual chapter topics and the bookmap and also the metadata elements. Hence defining the structure of the content.
There are numerous benefits of using DITA. Not only DITA is a standard but also it helps in creating, managing, and publishing the contents with ease.
![What is DITA XML? || [Beginners guide]](https://lh5.googleusercontent.com/pBblYxSazbHTTznLiT9ALcRnmsw3hIizX-MR5gMQdeKTpr-VWOSCRyYppXcIPXHe9aYYd_kP0m658X-_Dv1b_VSBV6yJsDPBfsMewMAoUnN1qFnb9EbOl_sRc6woXaD8Ji9Mt1dw=w180)
![What is DITA XML? || [Beginners guide]](https://lh5.googleusercontent.com/pBblYxSazbHTTznLiT9ALcRnmsw3hIizX-MR5gMQdeKTpr-VWOSCRyYppXcIPXHe9aYYd_kP0m658X-_Dv1b_VSBV6yJsDPBfsMewMAoUnN1qFnb9EbOl_sRc6woXaD8Ji9Mt1dw=w480)
0 Comments