Creating structured documents

with DITA and Teamcenter’s content

management solution

White Paper

Publishing groups by necessity develop guidelines, processes and

a common architecture to author and publish documents.
Traditionally, this has led to detailed content structures, which
impose significant overhead on document contributors. An
alternative is now available called the Darwin Information Typing
Architecture (DITA), This alternative enables publication groups to
rapidly implement XML and content management, as well as
dramatically improve the way source content is managed across a
product document’s lifecycle. With this in mind, Siemens PLM
Software provides DITA support for the Teamcenter® suite’s content
management applications.

Issued by: Siemens PLM Software. © 2010. Siemens Product Lifecycle Management Software Inc. All rights reserved.
White Paper | Creating structured documents with DITA and Teamcenter’s content management solution 2

Contents

Executive summary .............................................................................3

Introducing DITA ..................................................................................4

DITA concepts .................................................................................4

DITA structure .................................................................................5

Using Teamcenter to create and manage DITA documents ..................7

Using DITA maps .............................................................................7

Creating DITA specializations in Teamcenter’s content

management module ....................................................................10

Publishing DITA documents from Teamcenter’s content

management module ....................................................................10

DITA benefits .....................................................................................11

Conclusion .........................................................................................12

References.........................................................................................13

Issued by: Siemens PLM Software. © 2010. Siemens Product Lifecycle Management Software Inc. All rights reserved.
White Paper | Creating structured documents with DITA and Teamcenter’s content management solution 3

Executive summary

Publishing groups by necessity develop common higher level. Similarly, departmental requirements
guidelines and processes, as well as a common for functionality and content are handled using
architecture, for their contributors. Organizations specializations specific to each group. Unlike the first
that deal with the interchange of content have two option, this approach facilitates extensibility without
options. as much impact to the different groups involved.
This is because changes can be handled internally,
One option enables them to build a very detailed,
without significant impact to the generic, high-level
complex document type definition (DTD) that takes
architectures involved. The Darwin Information
into account all possibilities and requirements for all
Typing Architecture (DITA) provides this extensibility
of the different content and organizations involved in
and functionality.
developing product information. S1000D is an
example of this type of DTD. S1000D was developed DITA documents are composed of self-contained
to support the creation and publication of complex topics. These topics are available for re-use and
systems documentation, as well as the interchange of referencing, as are traditional content objects.
this documentation between organizations and However, because they are self-contained, there are
content management systems. Unfortunately, this changes involved in the way technical writers create
solution comes with a price. It is highly rigid, very specific portions of a document and compile the
large, and imposes significant overhead on authors document; these considerations require adaptation
and systems, especially if an organization directly from traditional document organization and
uses it for authoring. In addition, changes to the DTD writing styles.
require careful monitoring and maintenance over-
Teamcenter’s content management solution
head because of the number of people impacted and
combines DITA with Teamcenter’s ability to manage
the level of detail involved.
the relationships between engineering source
The second option is to use a more generic DTD that materials and structured content. The resulting
can be specialized to support specific functionality solution enables publication groups to quickly and
for different departments. The ability to create and easily migrate from traditional publishing methods to
interchange content in this instance is managed at a structured authoring.

Issued by: Siemens PLM Software. © 2010. Siemens Product Lifecycle Management Software Inc. All rights reserved.
White Paper | Creating structured documents with DITA and Teamcenter’s content management solution 4

Introducing DITA

From the beginning, the Darwin Information Typing DITA concepts

Architecture (DITA) was developed to be more then
“just another DTD” document type definition. Because DITA is more than another markup language defined
optimization of the content development process is in XML. To understand DITA’s value, it is useful to
directly related to a company’s specific prod- have a look at the meaning and derivation of its
uct/service line and its internal document develop- name.
ment processes, the number of universal DTDs is very
small. However, the efficiencies that can be realized
by publications groups have a direct relationship to D The letter D was chosen for the British naturalist
the amount of DTD and schema customizations they Charles Robert Darwin. Darwin achieved lasting
can implement to support their specific needs. fame for his “evolution theory,” which states that
By the same token, the delivery formats and systems species develop by inheriting their experiences
used to deliver that information must be customized from previous generations. This focus on inheri-
to a company’s DTDs and specific customer-base, tance made Charles Darwin the eponym for the
product and training needs. These requirements Darwin Information Typing Architecture.
affect everything from writing methods to content DITA enables users to create new markup
management schemes and authoring and publishing elements that are inherited from the basic DITA
application choices. elements. This inheritance facilitates individual
IBM had dealt with the issues that resulted from the DITA applications for specific needs, called
implementation of a detailed, custom DTD that “specializations.” A new element is a specialized
supported multiple departments. This effort focused variant of its basic element.
on the second content interchange option, and DITA IT Information Typing is an essential principle in
was the result. This standard became more than just a DITA that facilitates modular structuring and
DTD or schema. It included a number of concepts and functional marking of information.
an architecture that provided specialization for
department or targeted user functionality. It also In DITA, a complete document consists of
provided the ability to create and manage topics for many information modules, with each module
re-use that was directly in line with typical subject containing content specific to one topic. These
matter expertise document development used by information modules are called “topics” in DITA.
many technical publications groups. A The letter A stands for “architecture,” which
After testing and further development, IBM recog- signifies the collaboration of many different
nized the potential advantages of the standard for components in one complex system, such as
other organizations and proposed DITA to the the construction of a house or the development
Organization of the Advancement of Structured of software.
Information Standards (OASIS) in March, 2004. The DITA includes recommendations and concepts
OASIS DITA Technical Committee approved DITA as an regarding information organization, publishing and
official OASIS standard in June, 2005. exchange.

Issued by: Siemens PLM Software. © 2010. Siemens Product Lifecycle Management Software Inc. All rights reserved.
White Paper | Creating structured documents with DITA and Teamcenter’s content management solution 5

DITA structure To enable users to store and create more specific

types of information in typed topics, DITA offers three
A structured document consists of at least three further information types: concept, task and refer-
different structure levels: the entire document, the ence. Each of these three information types applies to
information modules within the document and the a specific DITA topic type, with relationships to other
vocabulary available in the information modules. DITA topic types as diagrammed in Figure 1. These
comes with one solution for each of these three information types represent specializations of topic
structure levels. and provide specific structures relative to procedural,
conceptual and reference material. They also ensure
DITA arranges information in unique, self-contained proper contextual usage of the topic in multiple
information modules called “topics”. Each DITA documents or DITA maps.
topic should only contain information specific to the
subject covered by that topic. Topics have no internal
hierarchical nesting. Instead, elements and attributes
that define or directly support the type of information Topic
provided in that topic are available to authors as
they write.
Similar to many structured content solutions, DITA
can be used to reduce the copy/paste methods of
re-use (where content from one document or section Specialization
is copied into another). When authors wanted to
perform copy/paste operation using traditional
documents, all copies of the same content has to be
maintained in each document where the content was
pasted; traditional documents needed this extra
effort to account for future content changes and
ensure their consistency and quality. With DITA, Task Concept Reference
re-use occurs at a topic level. Information designers
can re-use a topic in a new information model and
the architecture will process it consistently in its new
Figure 1. The four DITA information types.
context. This allows the topic to be maintained in a
single location. Changes will be displayed appropriate
to their use in any DITA map or document.

Issued by: Siemens PLM Software. © 2010. Siemens Product Lifecycle Management Software Inc. All rights reserved.
White Paper | Creating structured documents with DITA and Teamcenter’s content management solution 6

Create topics in Teamcenter DITA mapping/ Publication

Content Management referencing topics

DITAmap: Topic: DITAmap: ACME Widget

ACME Widget Part 1 ACME Widget Owner’s Manual

Topic: Topic: Reference: Topic “Widget info” 1. About the Widget

Widget info Part 2
Reference: Concept “Description” 1.1 Part 1
Reference: Topic “Part 1” 1.2 Part 2
Concept: Task:
Maintenance Oil change Reference: Topic “Part 2” 2. Maintenance
Reference: Concept “Maintenance” 2.1 Change oil
Reference: Concept: Reference: Task “Change oil” 2.2 Replace valve
Dealer info Description Reference: Task “Replace valve” 2. Dealer info
Reference: Reference “Dealer info”
Topic: Task:
Part 3 Replace valve

Figure 2. Principle of nested topic references in a DITA map.

DITA maps For structured documents that consist of is always associated to its base element and to any
nested information containers such as chapters and element in its specialization hierarchy. Topics can be
sections, DITA enables users to nest references to specialized from the generic topic into new informa-
existing DITA topics in a DITA map. Figure 2 clarifies tion types and the new information types can be
the principle of nested topic references in a DITA map. extended into more specific information structures.
A maintenance task, training procedure and the
DITA specialization DITA specialization allows steps involved in an operation sequence can all be
customization of the existing DITA markup language extended from the generic topic.
for individual purposes without the need to change
the DITA standard. As a result, it is possible to adopt In the same way, by the substitution or effectivity of
DITA – which was originally designed for the software domain-specific vocabularies, the element vocabulary
development sector – in manufacturing, aerospace within a topic can be specialized or extended specific
and other industrial sectors by creating new elements to the information domain for which the topics are
via DITA specialization. The key to creating new developed. Specialized vocabularies might include
elements specific to your documentation needs is the programming languages, mechanical terms or
“class” attribute. operation codes for a system, which can be hidden or
displayed based on the user roles or context of the
Any DITA element can be extended into a new document.
element whose identifier gets added to the class
attribute through its DTD. In this way, a new element

Issued by: Siemens PLM Software. © 2010. Siemens Product Lifecycle Management Software Inc. All rights reserved.
White Paper | Creating structured documents with DITA and Teamcenter’s content management solution 7

Using Teamcenter to create and manage

DITA documents

can nest DITA topics from both a generic topic type

and from specialized topics to topics of the same
information type. The result is the inclusion of the
content from the nested topic in the parent topic. If
you were to create a reference to the parent topic
from a map, the nested topic would also be included
in that map.

Using DITA maps

Creating DITA maps Teamcenter’s content manage-

ment module provides two different publication-types
for DITA maps: editable and dynamic. Both publica-
tion types can easily be created in Teamcenter from
the rich client with simple menu and dialog options.
Figure 3. Creating DITA topics using Teamcenter’s content
management solution.

Teamcenter’s content management solution enables

you to create and manage topics and their relation-
ships provided in the DITA architecture and XML
schema or DTD. Topics can be created in both the
Teamcenter content management rich client or
by working directly in the integrated authoring
applications.
Teamcenter’s content management DITA module
provides the four standard DITA information types
(generic topic, concept, task and reference) out of the
box. You can also create a DITA composite document
that contains DITA topics of any information type. Figure 4. Creating
Teamcenter’s content management module provides DITA maps in
Teamcenter’s content
two ways to re-use an existing DITA topic within other
management module.
DITA topics: referencing or nesting content.
Teamcenter’s content management module also
enables you to assemble topics using topic references The difference between the two map types is
in DITA maps. Because nesting topic references within apparent when creating the content of the particular
different information types is allowed in a DITA map, DITA map.
it is also possible to drop a topic onto a topic of a
Editable DITA maps Because DITA maps are XML
different information type, which results in a refer-
files, you can edit the content of an editable DITA
ence relationship between them.
map in any XML editor. Teamcenter’s content
It is possible to nest existing topics in Teamcenter by management module delivers the DITA map docu-
dragging a topic and dropping it onto another topic in ment type definition (DTD) automatically to the XML
Teamcenter’s content management rich client. You editor, where the author creates valid DITA map

Issued by: Siemens PLM Software. © 2010. Siemens Product Lifecycle Management Software Inc. All rights reserved.
White Paper | Creating structured documents with DITA and Teamcenter’s content management solution 8

contents. Siemens PLM Software recommends the use Teamcenter enables authors to select DITA concept
of an XML editor with DITA support (such as XMetaL task reference and generic topics in the client and
Author Enterprise Edition) because these applications generate XML topic references into the clipboard.
will assist the author with DITA-specific WYSIWYG These XML topic references are pasted into a
styling and timesaving features created especially for DITA map opened in an XML editor via the ordinary
the creation of DITA maps. paste function.
To support the author in creating the XML elements Teamcenter’s content management solution gener-
for the topic references inside a DITA map, ates topic references for the selected topics.

Create topics in Teamcenter Copy topics as

Content Management reference to clipboard

DITAmap: Topic:
ACME Widget Part 1

Topic: Topic:
Widget info Part 2 <topicref href=”Part 1”/>
<topicref href=“Change oil”/>
Concept: Task: <topicref href=“Dealer info”/>
Maintenance Oil change

Reference: Concept:
Dealer info Description

Topic: Task:
Part 3 Replace valve

Figure 5. Copying Teamcenter content management topics as

topic references.

Issued by: Siemens PLM Software. © 2010. Siemens Product Lifecycle Management Software Inc. All rights reserved.
White Paper | Creating structured documents with DITA and Teamcenter’s content management solution 9

Dynamic DITA maps Teamcenter also provides a way

to add topic references to DITA maps directly in the
Teamcenter content management client by dragging
existing topics and dropping them onto a dynamic
DITA map publication. Teamcenter then automatically
inserts references between the topics and the
dynamic DITA map.

Figure 6. Dropping a topic onto a dynamic DITA map.

You can use Teamcenter’s content management

module to expand and collapse related topics and
publications while browsing the structure of a
dynamic DITA map. If a topic with references to other
topics is dropped into a dynamic DITA map, the DITA
map will get just one reference – but it will use the
entire underlying structure of the dropped topic. In
Figure 6, the drag and drop would cause one addi-
tional reference to the dynamic DITA map, but the
whole underlying structure of the selected task would
be used in the DITA map.

Issued by: Siemens PLM Software. © 2010. Siemens Product Lifecycle Management Software Inc. All rights reserved.
White Paper | Creating structured documents with DITA and Teamcenter’s content management solution 10

Figure 7. Structure expand of a dynamic DITA map.

Creating DITA specializations in standard XSL styles – will be done on top of the
Teamcenter’s content management Open Toolkit without changing the application. This
guarantees full Open Toolkit support and an open
module
interface to every DITA change or enhancement
performed in the DITA Open Toolkit.
Users can easily register new DITA specializations in
Teamcenter’s content management module. This task
The DITA standard includes a solution for conditional
requires several basic Teamcenter content manage-
publishing, also known as “effectivity” or “filtering”.
ment administration skills (such as creating new
You can exclude specific contents in a DITA publica-
document types and attaching schemas) and needs
tion via “ditaval” files. Using Teamcenter’s content
to be done in the Teamcenter content management
management module, you can create, edit and
administrator client. See the “Teamcenter Content
manage ditaval filters and use them in publishing
Management Administration Manual” for further
a DITA document. Teamcenter supports the standard
information.
attributes – including platform, product, audience,
and otherprops as well as importance, rev and
status – available in DITA.
Publishing DITA documents from
Teamcenter’s content management Each ditaval filter object can be related to both
module editable and dynamic DITA maps in Teamcenter’s
content management module via drag and drop.
Teamcenter’s content management module integrates While publishing a DITA document with related
the DITA Open Toolkit (available at http://dita- ditaval filter objects, Teamcenter composes the topics
ot.sourceforge.net/) and uses it for publishing DITA according to the DITA ditaval to determine what
documents. Any further developments – e.g., in the conditional text will be included in the document.

Issued by: Siemens PLM Software. © 2010. Siemens Product Lifecycle Management Software Inc. All rights reserved.
White Paper | Creating structured documents with DITA and Teamcenter’s content management solution 11

DITA benefits

The DITA architecture and its standard provide Because the standard begins with a set of general
numerous benefits, especially to organizations that structures, whose characteristics are inherited by any
are migrating to structured content authoring and specializations, any specialized topic type can be
publishing for the first time. They also include vari- treated as a more generic type for common
ous recommendations and best practices for imple- processing.
mentation.
The topic-oriented nature of DITA lends itself well to
Traditionally, the development of DTDs and schemas re-use and to both print and online delivery; this is
involved information modeling, centered on existing one of the reasons it is being rapidly adopted for
and legacy writing and publishing processes and software product documentation. Keep in mind that
tools. This approach often reflects a “way we’ve moving from a linear document model to a topic-
always done it” attitude. Based on previous experi- oriented model is a significant adjustment. Organiza-
ence with complex DTDs, IBM indicated that “The tions that traditionally produce long linear documents
ideal for future extensibility in DTDs for technical and do not have a compelling reason to adopt a topic-
information (or any information that is continually oriented model would generally find it easier to use
exploited at the leading edge of technology) is to non-topic-oriented XML document types. If your
build the fewest possible presumptions about the customers require you to use an industry-specific
top-down processing system into the design of DTD, such as S1000D, it would be easier to modify
1
the DTD.” that standard to meet a technical publication group’s
writing requirements than to modify DITA and
Instead of requiring users to learn large, complex
provide transforms to convert from DITA to the
data structures, DITA’s topic-centric design enables
standard structure; these options should be analyzed
users to quickly become familiar with only those
carefully before implementing either option.
elements that are necessary in the topic types they
need for their jobs. This aspect of the standard has If you are already using XML and DTDs, and they meet
benefits from training and implementation through your requirements, there may be no increased benefit
the publishing and management phases, as support- in moving to DITA. If you are in a position of selecting
ing processes and transforms or templates need to DocBook versus DITA as your first structured author-
only deal with structures specific to their needs. ing system, you will find greater tool support and
momentum behind DITA than other recent standards,
although almost all systems support traditional
standards such as DocBook.

Issued by: Siemens PLM Software. © 2010. Siemens Product Lifecycle Management Software Inc. All rights reserved.
White Paper | Creating structured documents with DITA and Teamcenter’s content management solution 12

Conclusion

The DITA standard is rapidly gaining world-wide DITA is a comparatively easy-to-learn, significantly
acceptance for implementing and exchanging XML- easier to implement, structured authoring alternative
based content and supporting content management to cumbersome industry standards that focus on
and publishing functions. Teamcenter’s content interchange. Siemens PLM Software combines DITA
management DITA module supports requirements for with Teamcenter’s ability to relate product informa-
a DITA-compliant, complete CMS product suite. tion topics directly to the engineering source product
Teamcenter enables you to rapidly implement a data, enabling users to store, version and manage
productive solution for structured technical publica- those topics directly in the engineering product
tions management based on a standard template. life-cycle management environment. This gives you
Users are provided with the ability to create, update, an unprecedented opportunity to improve time-to-
organize and version DITA topics without the need to market and reduce the risk of inaccurate or outdated
open an authoring or editing application. product information.
Teamcenter’s content management solution will be If interchange specifications are not required for
maintained along with the OASIS roadmap of future specific product documentation, DITA is a strong
DITA releases, ensuring ongoing conformance with candidate, especially for organizations that are just
future versions of the specification, as well as beginning to implement an XML writing and publica-
facilitating rapid access to new DITA capabilities. tion environment. For those environments that
Inclusion of the DITA concepts and architecture require interchange, but do not require compliance
directly within Teamcenter’s content management with the entire interchange specification, DITA with
rich client provides easy-to-use alternatives to specializations may still be applicable, with transfor-
creating and managing DITA maps in XML editors. mations to the industry standard for interchanging
product information.

Issued by: Siemens PLM Software. © 2010. Siemens Product Lifecycle Management Software Inc. All rights reserved.
White Paper | Creating structured documents with DITA and Teamcenter’s content management solution 13

References

1. “Introduction to the Darwin Information Typing Architecture:

Toward portable technical information”. March 2001; Don
Day, Michael Priestley, David Schell, of IBM Corporation.

About JustSystems

JustSystems is a leading global software provider with three

decades of successful innovation in office productivity,
information management, and consumer and enterprise
software. With over 2,500 customers worldwide, the company
is continuing a global expansion strategy based on its XMetaL
content lifecycle solutions. JustSystems is one of the 2009
KMWorld 100 Companies that Matter in Knowledge
Management, a 2009 EContent 100 member, and was
recognized on the 2009 KMWorld Trend-Setting Product list
for XMetaL. Major strategic partnerships include IBM, Siemens
and EMC.

Issued by: Siemens PLM Software. © 2010. Siemens Product Lifecycle Management Software Inc. All rights reserved.
About Siemens PLM Software

Siemens PLM Software, a business unit of the Siemens Industry

Automation Division, is a leading global provider of product
lifecycle management (PLM) software and services with
6.7 million licensed seats and more than 69,500 customers
worldwide. Headquartered in Plano, Texas, Siemens PLM
Software works collaboratively with companies to deliver open
solutions that help them turn more ideas into successful
products. For more information on Siemens PLM Software
products and services, visit www.siemens.com/plm.

© 2010 Siemens Product Lifecycle Management

Siemens PLM Software Software Inc. All rights reserved. Siemens and the
Siemens logo are registered trademarks of Siemens AG.
Headquarters Americas Europe Asia-Pacific D-Cubed, Femap, Geolus, GO PLM, I-deas, Insight, JT,
Granite Park One Granite Park One 3 Knoll Road Suites 6804-8, 68/F NX, Parasolid, Solid Edge, Teamcenter, Tecnomatix and
5800 Granite Parkway 5800 Granite Parkway Camberley Central Plaza Velocity Series are trademarks or registered trademarks
Suite 600 Suite 600 Surrey GU15 3SY 18 Harbour Road
of Siemens Product Lifecycle Management Software
Plano, TX 75024 Plano, TX 75024 United Kingdom WanChai
USA USA 44 (0) 1276 702000 Hong Kong Inc. or its subsidiaries in the United States and in other
972 987 3000 800 498 5351 Fax 44 (0) 1276 702130 852 2230 3333 countries. All other logos, trademarks, registered
Fax 972 987 3398 Fax 972 987 3398 Fax 852 2230 3210 trademarks or service marks used herein are the
property of their respective holders.
www.siemens.com/plm
X3 22632 12/10 C