The document discusses using DITA (Darwin Information Typing Architecture) for technical documentation. It describes how DITA allows structuring content into modular topics and maps to generate information. DITA supports features like content reuse through conditions, and multi-lingual content through language tags. Content management systems like SDL LiveContent can store and publish DITA content, including maintaining common information through globally unique IDs for topics in different languages. This allows technical documentation to be delivered to customers in multiple languages.

1. DITA (Darwin Information Typing Architecture) - Flexible and Structured approach
for generating Technical Documentation
A White Paper
11/01/2016
Contents
1.Introduction / Background............................................................................................................3
2.Abstract / Business Case...............................................................................................................3
3.Problem Statement / Introduction.................................................................................................4
Different customers who are responsible for accepting a newly released products wants more
accurate, well-formed and structured product information to be delivered even before the
product go live. Most of the end users get basic understanding of the product on social
media so that they can be well equipped with all the information before getting the product.
Also they review the comments of existing customers who are using the same products,
which in turn make the whole scenario competitive one for different companies releasing
their products in markets. ........................................................................................................4
Also for the new product to be accepted in wide geographical region the technical
documentation should exist as well as published in multiple language. It’s a must criterion for
any released product to sustain in the market for a long time..................................................4
4. Proposed Solution(s) ................................................................................................................5
a.Introduction of Solution........................................................................................................5
DITA (Darwin Information Typing Architecture) has emerged as most flexible and reliable
approach in content organization across companies. It allows us to order, reorder and nest
different topics to generate more structured information’s for a technical documentation..............5
b.Application of Solution.........................................................................................................5
5.Future Direction / Long-Term Focus..........................................................................................10
In above example the title is present in different language for a product, however other
information are same such as the operating system on which product is supported and their
version. Same GUID for multiple language versions is used while publishing these topics so
as to reuse the common content. ...........................................................................................15
6.Conclusion...................................................................................................................................15
Abbreviation:..................................................................................................................................16
Appendices.....................................................................................................................................16
Appendix a – Authors............................................................................................................16
Appendix b – References........................................................................................................16
6/26/2016 Page 1

2. 6/26/2016 Page 2

3. 1.Introduction / Background
With increase in number of delivery channels, such as the Web, Mobile Phones,
tablets, most of the industry sectors began to realize that their traditional
documentation and publishing methodologies are not capable of providing much
information or was too complex for an inexperienced consumer to comprehend in
less time. It became increasingly obvious that a better solution was needed
which would provide structured and modular content, targeting wide range of
consumers.
Initially, many firms used XML as the solution for transforming their technical
documentation, as most of the content was narrative. But, birth of social media
across geographical regions and a significant increase in number of
equipment’s, compelled them to have a XML schema which is more modular and
structured. For example, Software sector alone dominates 30% use of a
modular and structured XML in creating technical documentation including
tech giants like Adobe, Codex, DITA Exchange and Quark. Apart from this,
other leading sectors are also in the league including Aerospace/Defense,
Data Warehousing, and Sensor Manufacturer.
2.Abstract / Business Case
The paper highlights one of the most reliable and reusable XML schema being
adopted across the industries for creating technical documentation. It will also
talk about best practices to be followed as well as comparison of this XML
Schema with other available schemas. The paper will also describe the
architecture of content management system which is helpful in reusing the
technical documentation generated by XML Schemas in different geographical
region.
6/26/2016 Page 3

4. 3.Problem Statement / Introduction
• Different customers who are responsible for accepting a newly released
products wants more accurate, well-formed and structured product information to
be delivered even before the product go live. Most of the end users get basic
understanding of the product on social media so that they can be well equipped
with all the information before getting the product. Also they review the
comments of existing customers who are using the same products, which in turn
make the whole scenario competitive one for different companies releasing their
products in markets.
• Also for the new product to be accepted in wide geographical region the
technical documentation should exist as well as published in multiple language.
It’s a must criterion for any released product to sustain in the market for a long
time.
• Making the structured and modular document is not the only concern for
companies, but delivering it to localized consumers and to reuse it was another
big challenge.
• The traditional documentation which most of the firms are using is not capable of
providing such rich structured information and in maximum cases becomes
bottle neck in pre-release and post-release of a product.
• As different companies are launching their products in every geographical
markets, user acceptance for these products in different language was a
challenging task as the users are present globally. For example suppose a
company is planning to releases new Ink jet printer in Israel but the technical
documentation is only available in English and people speak only Hebrew
language in Israel.
In order to give a strong impact to user, a more streamlined process needs to be
adopted which should target the customer diversely so that the problems stated
above can be addressed.
6/26/2016 Page 4

5. 4. Proposed Solution(s)
a. Introduction of Solution
• DITA (Darwin Information Typing Architecture) has emerged as most flexible
and reliable approach in content organization across companies. It allows us to
order, reorder and nest different topics to generate more structured
information’s for a technical documentation.
For example many companies such as IBM, HP, Kodak, and NetApp are using
DITA for their manuals, reference guides and online help. There is significant
increase in adoption of DITA in other technology sectors, such as
Telecommunications (Nokia, Research in Motion), Computing Hardware (Dell,
Epson, and Xerox), Networking Equipment (Cisco, Juniper Networks), Data
Storage (EMC, Hitachi Data Solutions) and Consumer Electronics (Apple,
Samsung).
b. Application of Solution
DITA offers following features that makes the technical design documentation
more structured and modular.
i> DITA – Organizing content into Topic and Map
Organizing the content or small chunks of data into small sections and merging
inside a topic is primary task of DITA as shown below in the sample example:
<concept id="What is DITA">
<Title>DITA-Architecture for structured Information</title>
<author>XYZ</author>
6/26/2016 Page 5

6. <metadata> Allows consumer to search based on some information such
as product category, keywords, product-info</metadata>
<shortdesc>This type of topic provides basic information</shortdesc>
<language>English</language>
</concept>
As shown above in code snippet, DITA provides content creators with a facility
for creating a topic and tagging objects with metadata. Here the content author
describe what the content is about (“descriptive metadata”), as well as assign
properties like who created the content, when, in what language, and for which
audience (“administrative metadata”).
To make complex XML containing nested information more structured, generally
Maps are used. Maps contain references for all the related topics. The basic
structure is shown below:
<Map>
<Title>Environment to install a product </title>
<topicmeta>
<author>ABC</author>
<publisher>XYZ</publisher>
</topicmeta>
6/26/2016 Page 6

7. <topicref href="env_info.dita"/>
<topicref href="windows_Installation_manual.dita">
<topicref href= Unix_Installation_manual.dita">
</topicref>
</map>
In above examples maps contains reference to different topics using the
attribute ‘topicref’ which itself is a DITA topic containing more structured
information for product installation in different platform such as windows
and Unix.
Above figure depicts a Software-Item Map containing software Item topics
as references in a CMS. These topics contain information about
Installation Instruction, Release Notes manuals etc. of product.
The above topics in figure are present as an attachment for a software
product in XML format as shown below after getting transformed into
DITA.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
6/26/2016 Page 7

8. <collection collection-ID="COL24143" partner-update-type="MODIFIED"
soar-msg-ID="SOAR-1413792262177" state="APPROVED" submittal-
group-oid="submittal group 67" submittal-type-oid="1"><collection-
title>Structure of release notes</collection-title>
<software-item item-ID="vc-53540-1">
<attachments>
<attachment><attachment-title>vc-53540-1_Notes</attachment-title>
<authors><author>xingyu_chen</author>
</authors>
<document-types><document-type oid="25">Release Notes</document-
type>
</document-types>
<languages><language language-iso-code="zh" oid="2"><language-in-
English>Chinese</language-in-English>
<character-set-in-English>Simplified</character-set-in-English>
<local-language>Chinese</local-language>
<local-character-set>Simplified</local-character-set>
6/26/2016 Page 8

9. </language>
</languages>
</attachment>
</attachments>
<software-item>
ii> DITA – Content Reuse
DITA also allows the writer to set conditions for the products, version,
and platforms. The author can then reuse these conditions to produce
different outputs for different types of users.
For example suppose there is installation manual page for a software
product that is available in both windows and Unix platform. The
functionality of the application is similar in all operating systems, but
there are a few differences between the two. By using
the platform attribute, we can indicate which operating system the topic
covers. When we publish our files, we can use the platform attribute to
produce documentation for both operating systems.
<p audience="administrator">Set the configuration options:
<ul>
<li product="extendedprod">Set foo to bar</li>
<li product="basicprod extendedprod">Set your blink rate</li>
6/26/2016 Page 9

10. <li>Do some other stuff</li>
<li platform="Linux">Do a special thing for Linux</li>
</ul>
</p>
In the above example we are specifically mentioning to “do a special task
in linux” platform.
iii> DITA-Multi-Lingual Content
DITA provides a feature for creating multi lingual documents, each language
has its own topic as shown below, with file names or reference names (in a
CMS) annotated using the xml-lang as shown below:
<concept xml: lang="en-US"> For English version Topics
<concept xml: lang="ko-KR"> For Korean Version Topics
5.Future Direction / Long-Term Focus
Publishing DITA’s dynamically
Only a structured content is not going to solve problem stated above, a CCMS is
required where this structured content can be stored, reused and published.
Many CMSes are available which manages Entire DITA Documentation Process.
6/26/2016 Page 10

11. DITA CMS, SiberSafe 7, SDL live Content are some of the examples.
Above figure depicts the comparison between different CMSes present in
market. Some of the comparisons are analyzed below:
• SaaS and Hosted systems do not require the capital outlay necessary for
buying servers and software, though we can expect to be tied to a service
contract. Standalone systems offer the possibility of greater flexibility and
security, though along with the additional IT and development costs that come
with it.
• The type of database in which the XML information is stored is another factor
that can play into the decision-making process of choosing a DITA-capable
CMS. MySQL is the database used behind blogs and CMS-based websites.
• Some systems are not just DITA-capable but can also be used for other
documentation specifications, such as S1000D, ATA. It can be an added
advantage.
Each CCMS has feature to store DITA and reuse it but among them SDL Live
content provides some of unique features which are listed below.
6/26/2016 Page 11
Name Manufacturer DB Type CMS
Type
Core
Software
Handles
Workflow
Mgmt.
Built-in
Standalone
or SaaS
Astoria On-
Demand
Astoria
Software
Native
XML
CCMS DITA Y SaaS or
Hosted
DITA CMS Ixiasoft Native
XML
(TEXTML
Server)
CCMS DITA Y Standalone
IBM FileNet
P8
IBM Relationa
l (Content
Engine)
ECMS
with
suppor
t for
DITA
DITA Y Standalone
SDL
LiveConten
t Architect
SDL Native
XML
CCMS DITA Y SaaS,
Hosted or
Standalone

12. • It manages DITA content in any language, so that it can be easily reused,
shared, and can be dynamically published to the appropriate channels such as
PDFs or web form in any geographical region.
• It has a feature of Globally Unique IDs (GUIDs), which uses the previously
translated content and enables easier tracking of content relationships.
Case Study:
Problem:
Suppose a software product is going to be released having installation manual in
English version targeted for English audience, now if the same product is
launched in Korean Market then there occurs a problem where a person
understands only Korean.
Solution
We need to have a Korean Installation manual, having other details of product
intact as English version. This helps an individual to have better understanding
about the product being released in their regional market.
Outcomes:
Now SDL Live content manages this by keeping the Globally Unique IDs
(GUIDs) for English and Korean version of Installation Manual same so that
other details which are common for that product can be reused.
Below shows the sample structure of how topics and maps is stored in SDL Live
Content.
6/26/2016 Page 12

13. Here SDL Live content stores topic in multiple languages for installation manuals of a
newly released product .Rest other information’s are same and can be reused.
Inside DITA topics, xml: Lang attribute is the identifier for SDL to maintain different
language version of installation manual keeping their GUIDs same for a particular
software-product.
For example
Chinese DITA Topics for a Product
<?xml version="1.0" encoding="UTF-16"?><!DOCTYPE concept PUBLIC
"-//OASIS//DTD DITA Concept//EN" "concept.dtd"[]><?ish ishref="GUID-
5FF79352-6BAD-4DC2-A91F-305AFC31A019" version="1" lang="zh-CN"?
><concept id="GUID-5FF79352-6BAD-4DC2-A91F-305AFC31A019" xml:lang="zh-
CN">
<title cid="1j6Txb">芯片组驱动 (Intel Chipset Installation Utility for ICH7)</title>
<prolog>
<category>Software item</category>
<data name="ITEMID" value="wk-119492-1"/>
<data name="OPERATINGSYSTEM" value="Microsoft Windows 7 Professional
(32-bit)"/>
<data name="SWVERSION" value="1.00.72.04 Rev. A"/>
</prolog>
6/26/2016 Page 13

14. </concept>
Korean DITA Topics for same Product
<?xml version="1.0" encoding="UTF-16"?><!DOCTYPE concept PUBLIC
"-//OASIS//DTD DITA Concept//EN" "concept.dtd"[]><?ish ishref="GUID-
5FF79352-6BAD-4DC2-A91F-305AFC31A019" version="1" lang="ko-KR"?
><concept id="GUID-5FF79352-6BAD-4DC2-A91F-305AFC31A019" xml:lang="ko-
KR">
<title cid="aUxVT">ICH7 용 Intel 칩셋 설치 유틸리티</title>
<prolog>
<category>Software item</category>
<data name="ITEMID" value="wk-119492-1"/>
<data name="OPERATINGSYSTEM" value="Microsoft Windows 7 Professional
(32-bit)"/>
<data name="SWVERSION" value="1.00.72.04 Rev. A"/>
</prolog>
</concept>
6/26/2016 Page 14

15. In above example the title is present in different language for a product, however
other information are same such as the operating system on which product is
supported and their version. Same GUID for multiple language versions is used
while publishing these topics so as to reuse the common content.
6.Conclusion
There are lot of factors which play a major role when a product releases in
market; most important and crucial one is its user acceptance. When a company
release its product their target is to reach to maximum user globally. So, it’s an
essential question for any Company which have been investing a lot of capital in
the call center support so as to help the consumers to understand a product;
whether they want to reiterate the methodology or they want to operate smartly
by adopting a modular and structured architecture to save cost and time.
6/26/2016 Page 15

16. Abbreviation:
CCMS: Component Content Management System
DITA: Darwin Information Typing Architecture
Appendices
Appendix a – Authors
Saurabh Ranjan
Appendix b – References
http://www.ibm.com/developerworks/library/x-dita1/
http://docs.oasis-open.org/dita/v1.2/os/spec/DITA1.2-spec.html
http://www.xmlmind.com/tutorials/DITA/
6/26/2016 Page 16