1. DITA Quick Start Workshop for
Authors: Part 2
Joe Gelb
August 27, 2013

2. Who is this guy?
Joe Gelb
• Founder and President of Suite Solutions
Suite Solutions
Our Vision: Enable you to engage your customers by providing quick access to
relevant information: DITA provides the foundation
• Help companies get it right the first time
• XML-based Authoring/Publishing Solutions
• Enterprise Intelligent Dynamic Content: SuiteShare Social KB
• Consultancy, Systems Integration, Application Development
• Cross-Industry Expertise
• High Tech, Aerospace & Defense, Discrete Manufacturing
• Healthcare, Government
• Blue Chip Customer Base
• Hundreds of Person Years of Experience on Staff

3. Introduction to DITA:
Main Topics
Part I
 Introduction to XML
 Overview of DITA
Part II
• Topics: The Basic Information Types
• Maps: Assembling Topics into Deliverables
• Linking Methods

4. Topics: Basic Information Types
• Each topic answers a single question
• Three basic information types, specialized from the standard
topic:
• Concept
Background, descriptive, conceptual information that
explains what something is or how it works
Answers: “What is this?”
• Task
Step-by-step instructions for reaching a certain goal;
Answers: “How do I do this?
• Reference
Tables, lists, diagrams, process flows and other
information that must be easy to look up

5. Topics: Basic Information Types
• Additional topic types:
• Glossary Entry
glossentry
• Learning Topics
Plan, Overview, Content, Summary, Assessment
Other Specializations
Machine Industry Task, API, JavaAPI, Troubleshooting, and
more
Available as plug-ins from SourceForge

6. DITA Base Topic
Forms the basic topic structure, from which the other
information types are specialized

7. Basic Topic Elements
title Label for the topic; element also used to label sections,
examples, figures, tables, etc.
shortdesc Short description: purpose or theme of the topic; highly
recommended that all topics have one
abstract Allows a wider range of content than shortdesc
(new for DITA 1.1)
prolog Contains information about the topic entered by the author
or by machine
body Container for the main body of the topic
section Subset of information directly related to the topic; does not
represent hierarchy and cannot be nested
example Section with examples that illustrate or support the topic
related-links Links to related information

8. DITA Concept
Background, descriptive, conceptual information that
explains what something is or how it works

9. DITA Task
Step-by-step instructions for reaching a certain goal

10. DITA Task

11. DITA Task
Main taskbody elements
prereq Pre-requisite; things the
user needs to know or do
before starting the current
task
context Background information;
helps the user understand
the purpose of the task and
what they will gain by
completing the task; should
be brief
section General organizational
container for content which
can include a title
[1.2]

12. DITA Task
Main taskbody elements
step Action that the user must
follow to accomplish a task;
must contain a command
<cmd> element which
describes the particular
action
result Describes the expected
outcome for the task
example Examples that illustrate or
support the task
postreq Steps that the user should
do after the successful
completion of the task
[1.2]

13. DITA Task
Main step elements
note Calls attention to a
particular point
hazard
statement
Hazard warning
information, based on ANSI
and ISO standards
cmd Provides the active voice
instruction for completing
the step; should not be
more than one sentence.
info Provides additional
information about the step
substeps Allows you to break a step
into separate actions; avoid
wherever possible

14. DITA Task
Main step elements
tutorialinfo Additional information
that is useful when the
task is part of a tutorial
stepxmp Used to illustrate the step
choicetable Contains a series of
optional choices
available within the step
choices Used when the user will
need to choose one of
several actions while
performing the step
stepresult Provides information on
the expected outcome of
the step

15. DITA Reference
Tables, lists, diagrams, process flows and other information
that must be easy to look up

16. DITA Reference

17. DITA Reference
Main refbody elements
section Used to organize subsets of information that are directly
related to the topic; does not represent hierarchy
refsyn Contains syntax, signature content, or a brief, possibly
diagrammatic description of the subject's interface or high-
level structure
example Examples that illustrate or support the reference topic
table,
simpletable
Tabular information
properties Gives a list of properties for the subject; can include the
type, value, and a description
refbodydiv Container for grouping content; can be used for
specialization and reuse [1.2]

18. Topic Elements:
Short Description: shortdesc
• Generally output as the first paragraph in the topic
• Should be simple enough to be suitable for use as a link preview or
summary
• If first paragraph cannot be simple enough, use the <abstract> element
with <shortdesc> inside
• Highly recommended that all topics have one: if there is only one
paragraph in the topic, it is preferable to include a shortdesc and leave rest
empty
• Should be a single, concise paragraph with one or two sentences

19. Topic Elements:
Short Description: Recommended Content
Task Explain what the task helps users accomplish,
benefits, when the task is appropriate or why it is
necessary
Use complete sentences, not fragments
Concept Provide concise answer to “What is this?” or “Why do
I care about this?”
Should contain the main point of the concept
Use complete sentences, not fragments
Reference Describe what the reference item does, what it is,
what it is used for
If you use fragments, use consistent phrasing across
your content set

20. Topic Elements: Prolog
• Contains information about the topic as a
whole
• author information
• subject category
• Entered by the author or machine-
maintained
• Generally is not displayed in the published
output
• May be used by processes that generate
search indexes or customize navigation

21. Topic Elements: Prolog -> Metadata
• Provides information about
the content and subject of a
topic
• Index terms can be coded in
the <keywords> element

22. Body Elements
Support the most common types of content for topics
ph phrase; used to
organize content for
reuse or conditionalize
keyword identifies a keyword
xref cross-reference
dl definition list
desc description
pre, lines preformatted text
cite citation
q, lq quotation, long
quotation
sectiondiv Untitled containers [1.2]
table, simpletable
p paragraph
ol, ul ordered, un-ordered list
li list item in a <ul> or <ol>
sl simple list
sli list item in a <sl>
note calls attention to a
particular point
fig figure with an optional
title
image artwork; can be inline or
on next line
hazardstatement [1.2]

23. Domain Elements
Defined vocabularies for common use across different topic types
Programming apiname, codeblock, paraml, syntaxdiagram …
Software msgblock, cmdname, varname, filepath, userinput
User Interface uicontrol, menucascade, shortcut, wintitle, screen
Utilities imagemap, area, shape, coords
Indexing index-see, index-see-also, index-sort-as
Typographic b, u, i, tt (teletype), sup, sub
xNAL Elements for name and address [1.2]

24. Common Attributes
id anchor; target for references
conref component reference to an element within another topic
importance priority: obsolete | deprecated | high | low …
rev revision level of the element
status status of the element: new | changed | deleted …
outputclass role that the element is playing; used for output formatting
Conditional attributes: support conditional processing
audience intended audience for the element
product name of the product which the element applies
platform indicates operating system or hardware
otherprops can be used for any other properties
props root attribute meant to be specialized

25. Introduction to DITA:
Main Topics
 Introduction to XML
 Overview of DITA
 Topics: The Basic Information Types
• Maps: Assembling Topics into Deliverables
• Linking Methods

26. DITA Maps: Assembling Topics into
Deliverables
• Assemble any number of topics into sequences
for print or online delivery
• Organize topics into a hierarchy
• Heading levels based on context and
position, not the topics themselves
• Use sub-maps within maps
• Allows you to create building blocks
• Maps can be filtered using conditional
processing: master map re-use

27. • Can create different types of maps:
• Solution-oriented
How products and procedures work together
• Task-oriented
How to accomplish a specific goal
• Feature-oriented
What does a product or component do
• Map specializations
• Bookmap
• Learning
DITA Maps: Assembling Topics into
Deliverables

28. DITA Map
Organizes topics into sequential hierarchy and relationship tables

29. DITA Map
Main elements
topicref Identifies a DITA topic or other resource; may contain other
<topicref> elements, allowing you to express hierarchies
and relationships
topicmeta Defines the metadata that applies to a topic when it
appears in a map and to the other topics contained by the
same element that contains the <topicmeta> element
topichead Provides a title-only entry in a navigation map
topicgroup Creates groups of <topicref> elements without affecting
the hierarchy; typically used to identify groups for linking
and metadata without affecting the resulting toc/navigation
output
reltable Relationship table; defines relationships between topics

30. Bookmap
Creates deliverables that are structured like traditional print publications

31. Bookmap
Front and back matter

32. Introduction to DITA:
Main Topics
 Introduction to XML
 Overview of DITA
 Topics: The Basic Information Types
 Maps: Assembling Topics into Deliverables
• Linking Methods

33. Linking Methods
• Hierarchy links
• Cross-references: internal and external
• Related Links
• Component references: conref
• Indirect addressing: keys [DITA 1.2]

34. Hierarchy Links
• Based on hierarchy links in the map:
nested topicrefs
• Links to parent, children
• Generated automatically by the DITA Open Toolkit during
publishing
• Child links: includes title and short description

35. Cross-reference: <xref>
• Internal and external
• Best practice: reduce or eliminate usage of external cross-
references
• External link:
<xref href=“path/filename.dita#topicID/elementID”
• Internal link:
<xref href=“#elementID”

36. Related Link: <link>
• Related Links
• Listed in Topics in <related-links>
<link href=“path/filename.dita#topicID/elementID”
type=“task”
format=“dita”
scope=“local”>
<linktext>title override</linktext>
</link>

37. Relationship Tables
• Defines relationships between topics based on the table model of
rows, columns and cells
• Table cells can contain <topicref> elements, which are then related
to other <topicref> elements in the same row
• By default, is not output for navigation or TOC purposes; used only
to define relationships that can be expressed as topic-to-topic links
• Can be used with hierarchies and groups to manage all related
links in an information set

38. Relationship Tables
• Each row represents a
separate set of relationships
and links
• No relationship exists
between the rows in a table
• Topic references are not
needed in every cell within a
row
• Each cell can contain
multiple topic references
• Topic references can be
repeated in multiple rows

39. Content Reference: conref
• Replaces content of element with the content of another element
• Implemented as an attribute
• Component markup must be valid inside the element making the
reference
<note conref=“path/filename.dita#topicID/elementID”>

40. Conref Range
[DITA 1.2]
• Allows you to include a range of elements instead of a single element
• Use the conref attribute to reference the first element in the range, and
the new conrefend attribute to reference the last in the range

41. Conref Push
[DITA 1.2]
• Reverses the direction of reuse from a pull to a push
• Use the new conaction attribute to determine whether content is
rendered before, after, or in place of the element being referenced
• Useful for pushing content into preset content templates
<step conaction="pushreplace"
conref=“changingtheoil.dita#changeoil/removeoilfilter">
<cmd>Use the special wrench for tractors</cmd>
</step>

42. Indirect Key-based Addressing
[DITA 1.2]
• Layer of abstraction: resources addressed by references can be
defined at the DITA map level
• Allows relationships to resolve to different resources based on different
contexts: product-based, customer-based, subscription-based, etc.
• Links refer to key names, the keys are bound to resources via the map
• Different maps can bind the keys to different resources
• Keys defined using topicref or keydef elements
• Topics can be given symbolic names using the keys attribute

43. Defining Keys
Using keydef
• Topic will not be included in the map navigation
• Used for variable text
<keydef keys="oilterm" href=“oiltype.dita“ processing-
role="normal"/>
Using topicref
• Topic will also be included in the map navigation
<topicref keys="oilchange" href=“changingoil.dita" />

44. Linking from Terms and Keywords
• Can associate glossary and index term definitions in a map
• Entries may be referenced from other topics
<map>
<keydef keys=“gauge” href=“oil-gauge.dita”>
</map>
…
<p>Use the <term keyref=“guage”>oil gauge</term> to
measure the amount of oil currently in the
engine.</p>

45. Substituting Variable Content
• Variable text can be defined as keywords in the map
• Variable text can be used in different topics
<map>
<keydef keys=“oiltype”>
<topicmeta>
<keywords><keyword>10W-30</keyword></keywords>
</topicmeta>
</keydef>
</map>
…
<p>Only use <keyword keyref=“oiltype” /> in your vehicle.</p>

46. Producing Custom Documents
• Substitute for conditional processing
• Use conkeyref in topics to pull in pre-defined content
• Use a different map for each document variation to bind keys to the
proper pre-defined content
<p conkeyref=“oiltype”></p>
map
<map> <!-- this map is for cars -->
<keydef keys=“oiltype” href=“car-engine-oils.dita”>
</map>
car-engine-oils.dita
<p>Use only 10W-30 or 10W-40 in your car, depending on
…</p>

47. Introduction to DITA:
Main Topics
 Introduction to XML
 Overview of DITA
 Topics: The Basic Information Types
 Maps: Assembling Topics into Deliverables
 Linking Methods

48. DITA Quick Start
End of Part II
Join us for our upcoming webinars:
• Getting Started with the DITA Open Toolkit
• Getting Started with Information Architecture
• System Architecture of a Basic DITA Toolset
• Migrating to DITA: Building a Project Plan
• Migrating to DITA: Defining Your Style Sheet Requirements
• Migrating to DITA: Defining Your Conversion Requirements
• Migrating to DITA: Defining Your Translation Requirements
To learn how the DITA Quick Start Program can get you up and running:
http://www.suite-sol.com/pages/solutions/dita-quick-start.html

49. Be in touch
For additional information, contact:
Joe Gelb
solutions@suite-sol.com
U.S. Office EMEA Office
(609) 360-0650 +972-2-993-8054
www.suite-sol.com
Follow us on LinkedIn