What are DITA and DocBook?

What is structured content?

Structured content is a content that corresponds to a certain standard or specification. This means that it has predefined structure and it is organized according to predefined rules. The most commonly used way of expressing structured content is XML. This type of content allows it to be easily processed and transformed into other types of content.

What is DITA?

DITA or Darwin Information Typing Architecture is an open standard for technical documentation created by IBM. Content conforming to the DITA standard is a structured content. DITA content is organized as topics, so authoring in DITA is also called topic based authoring. Main DITA topics (or types) are for example Task, Concept, Reference, Glossary Entry, Troubleshooting. DITA defines also a bookmap, which is a container for DITA topics. For example for a physical book, the book itself can be represented in DITA as bookmap and the individual chapters as topics. In this case two different bookmaps can contain same topic, which is content modularization. DITA content can be published (or converted) in many other formats such as HTML, PDF, Microsoft's DOC (or DOCX), Open Office's ODT, or even to another standards for writing documentation like DocBook. There are variety of free and commercial tools for DITA content publishing. jAuthor is a DITA authoring tool that uses both the free and commercial toolkits for publishing.

Here is an example of a DITA document:

								  
<topic id="chapter_1" xml:lang="en-us">
    <title>Front View</title>
    <shortdesc>Car front view</shortdesc>
    <body>
        <section/>
        <p>
            <image placement="inline" src="images/front_view.png" width="300"/>
            <ol>
                <li >Fuel filter flap</li>
                <li >Roof antenna</li>
                <li >...</li>
            </ol>
        </p>
    </body>
</topic>

Now this topic can go in a separate file front_view.dita and can be included in a DITA bookmap like this:

								
<bookmap id="car_manual">
  <booktitle>
    <booklibrary>Manuals</booklibrary>
    <mainbooktitle>Vehicle Owner's Manual</mainbooktitle>
    <booktitlealt>Owner's Manual for vehicle</booktitlealt>
  </booktitle>
  <chapter href="front_view.dita"/>
</bookmap>

Similarly additional chapters can be added by referencing their files like this:

								
<bookmap id="car_manual">
  <booktitle>
    <booklibrary>Manuals</booklibrary>
    <mainbooktitle>Vehicle Owner's Manual</mainbooktitle>
    <booktitlealt>Owner's Manual for vehicle</booktitlealt>
  </booktitle>
  <chapter href="front_view.dita"/>
  <chapter href="side_view.dita"/>
  <chapter href="rear_view.dita"/>
</bookmap>

What is DocBook?

DocBook is a schema or markup language originally created for writing and publishing computer documentation. Content created according to the DocBook standard is also structured content. Some of DocBook's structural tags include: set, book, article, chapter, appendix and others. Similar to DITA, DocBook content can also be easily published (converted) in many other formats such as HTML, XHTML, EPUB, PDF, HTML Help and many others.

Here is an example of a DocBook document:


<article>
 <info>
   <title>Learning DITA and DocBook</title>
     <author>
       <personname>
         <firstname>John</firstname>
         <surname>Doe</surname>
       </personname>
     </author>
     <publisher>
       <publishername>jauthor.com</publishername>
     </publisher>
   <pubdate>2022</pubdate>
 </info>
   <section id="dita">
     <title>Learning DITA</title>
     <para>Introduction to DITA authoring...</para>
   </section>
   <section id="docbook">
     <title>Learning DocBook</title>
     <para>Introduction to DocBook authoring...</para>
   </section>
</article>

Creating a book including this article will look like this:


<book>
  <article>
   <info>
     <title>Learning DITA and DocBook</title>
	   <author>
	     <personname>
		   <firstname>John</firstname>
		   <surname>Doe</surname>
	     </personname>
	   </author>
	   <publisher>
	     <publishername>jauthor.com</publishername>
	   </publisher>
     <pubdate>2022</pubdate>
   </info>
     <section id="dita">
	   <title>Learning DITA</title>
	   <para>Introduction to DITA authoring...</para>
     </section>
     <section id="docbook">
	   <title>Learning DocBook</title>
	   <para>Introduction to DocBook authoring...</para>
     </section>
  </article>
</book>

Or in the following way if we save the article is in a separate file article.xml:


<book lang="en">
    <title>Technical Documentation Authoring</title>
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="article.xml"/>
</book>

Creating DITA and DocBook documentation with jAuthor

The quickest and easiest way to create DITA and DocBook documentation is by using jAuthor Lite. jAuthor Lite is free leightwight version of jAuthor for online documentation authoring. To start using the tool go to jAuthor Lite and click on "Sign Up" to register for free.

To get up to speed quickly after registering to the website, please check the Quick Start Guide available here:

jAuthor Lite Quick Start Guide

Other Specifications

S1000D

S1000D is a technical publication specification initially developed by the AeroSpace and Defence Industries Association of Europe (ASD) for creating documentation for military aircrafts. However it is currently globally recognized and it is used for civil products as well. It can also be used for non-technical publications. S1000D is an XML specification so it is provided in XML format. S1000D is maintained by the S1000D Steering Committee:

ASD - AeroSpace and Defence Industries Association of Europe
AIA - Aerospace Industries Association
ATA - Air Transport Association of America

The specification is based on international ISO, W3C, ATA standards and it is free to download and use.

The main concept in S1000D is the DataModule, which is a single unit of information for a specific part or product. Each module has specific code (SNS or Standard Numbering System) which is used to store it in a database (CSDB or Common Source DataBase) in XML format. The specific code is then used to retrieve the module. Variety of image and video formats are supported by the specification, which on their side are stored in CSDB and retrieved using ICN (Information Control Number)

The publication module on the other hand defines the content and structure of a publication by referencing data modules or other publication modules. Publication modules are identified by Publication Module Code or PMC.

S1000D will be supported in future versions of jAuthor.

(This page is constantly being updated)