1. 1
Introduction to DITA
Bernard Aschwanden
www.publishingsmarter.com
www.publishingsmarter.com2 2:55
Bernard Aschwanden
President of Publishing Smarter
Worked in docs and training since 1992
Consultant and trainer in CMS, XML, DITA,
and publishing technologies
STC Toronto Community Past President
www.publishingsmarter.com3 2:55
Publishing Smarter
Works with clients to improve content
creation, management, and distribution
workflows
Provides content analysis, legacy file
conversion, training, and support
Main goals are to reduce production costs,
improve document quality, and increase
employee productivity
Learner outcome
Understand core DITA
Present your team clear information about
DITA and the pro's and con's it offers
See DITA applied to real world doc examples
Deliver the right content, to the right
audience, at the right time, and in the right
format
www.publishingsmarter.com4 2:55
www.publishingsmarter.com5 2:56
My disclaimer
I will be making blanket statements about
DITA to keep things simple
Not all that I tell you will be 100% DITA, but
Slides are a reference, they go by quickly
Bonus materials may also be covered
About DITA
Summing up a complex idea in as
few slides as possible
2. 2
DITA should matter to you
A growing standard with vendor support
Adobe, JustSystems, Oxygen, Quark, third-party
Word support, and much more
More companies looking for DITA skills
Not just structured writing; best practices:
Planning content
Organizing information
Developing relationships
Using automation where it makes sense
www.publishingsmarter.com7 2:56
Setting the stage
Most of the people in attendance have likely
heard of DITA
There is a very short overview of DITA to put
everyone into a similar mindset to start
Summation and open QnA session
Bonus materials as time allows
www.publishingsmarter.com8 2:56
www.publishingsmarter.com9 2:56
DITA in a single slide
D is for Darwin
IT is for Information Typing
A is for Architecture
DITA is primarily about Topic, Maps, Specializations
Some included specializations include
concept, reference, task, glossary (topic based)
bookmap (map based)
various domains (software, programming)
Core ideas within DITA
www.publishingsmarter.com10 2:56
Maps
Used to plan, organize, and
publish
Reltables
Build relationships between
info in maps
Topics
Types of info in a map, generally
as task, concept, or reference
Specializations
Customize as needed if other
options are exhausted
Behind the scenes
www.publishingsmarter.com11 2:56
Maps
Used to plan, organize, and
publish
Reltables
Build relationships between
info in maps
Topics
Types of info in a map, generally
as task, concept, or reference
Specializations
Customize as needed if other
options are exhausted
Attributes
Writing DITA
Key ideas that writers should focus
on when starting
3. 3
Starting points for writers
topic: A meaningful, stand alone unit of
information, minimalist, well written
task: Procedural details (step-by-step
instructions)
concept: Background info users need to
know
reference: Quick access to facts
attributes: Metadata used to further define
elements
www.publishingsmarter.com 9:06 www.publishingsmarter.com14
Commonly used elements
paragraph elements
tgroup and table elements
body related elements
body
conbody
refbody
taskbody
section and example elements
xref element
list elements
ul
ol
li
figure and image elements
task related elements
prereq
context
steps
result
example
postreq
steps related elements
steps and steps-unordered
step
cmd
info
stepresult
tutorialinfo
www.publishingsmarter.com15 9:09
Key elements to start
Before starting common elements I like:
title is often a heading for the topic, (also used by
sections, examples, figures, tables)
shortdesc is an initial brief statement in a topic
that does NOT repeat the title, it enhances it
prolog is metadata or information about a topic
manage content
www.publishingsmarter.com16
Domain elements
typographicrelated
b, i, u, tt, sup, sub
programming related
codeph, codeblock, option,
kwd, var, parmname, synph,
oper, delim, sep, apiname,
parml, plentry, pt, pd,
syntaxdiagram, synblk,
groupseq, groupchoice,
groupcomp, fragment,
fragref, synnote, synnoteref,
repsep
software related
msgph, msgblock, msgnum,
cmdname,varname, filepath,
userinput, systemoutput
user interface related
uicontrol, wintitle,
menucascade,shortcut,
screen
utilitiesrelated
imagemap, area, coord,
shape
www.publishingsmarter.com17 9:19
Develop any DITA topic type
Write the high-level structure, with at least a
title, and (suggested) both a prolog and a
good short description
Populate specific content as it is provided
Task, Concept, Reference, Topic
The fantastic four of DITA
www.publishingsmarter.com 9:06
4. 4
www.publishingsmarter.com19 9:11
Tasks are core
Odds are people are doing things when they
discover a need to look up docs
Tasks are the most likely place users turn
Non-DITA Purist: The procedural stuff you
look up when you need to know how; often
used by trainers or self-study guides
www.publishingsmarter.com20 9:11
According to DITA: task
An answer to how that tells the user just
what to do and the order in which to do it
Step-by-step instructions that enables a user
to actually do something
www.publishingsmarter.com21 9:12
DITA task structure
Structure
title
shortdesc (or abstract)
prolog
taskbody
prerequisite
context
step
result
postrequisite
related links
nested topics
TASK
www.publishingsmarter.com22 9:13
Concepts
If people are wondering why they should do
something, or the benefits, then a concept is
likely needed
Non-DITA Purist
tells you what it is and why you want it with
great background info
www.publishingsmarter.com23 9:14
According to DITA: concept
Answers the question what is or why by
detailing information about something
Initial information that users must know
before they can successfully work
Supports the task by providing an
explanation that is outside the scope of the
task
www.publishingsmarter.com24 9:15
DITA concept structure
Structure
title
shortdesc (or abstract)
prolog
conbody
sections and examples
block-levelelements
phrases and keywords
images and multimedia
related links
nested topics
CONCEPT
5. 5
www.publishingsmarter.com25 9:16
References
Non-DITA Purist: The tech stuff you look up
when you know the big picture (concept)
specific details
www.publishingsmarter.com26 9:16
According to DITA: reference
Quick access to facts
Tables, lists, alphabetical
Users should be able to scan quickly and find
information
Often technical or background information
www.publishingsmarter.com27 9:17
DITA reference structure
Structure
title
shortdesc (or abstract)
prolog
refbody
sections and examples
syntax
tables
properties
related links
nested topics
REFERENCE
www.publishingsmarter.com28 9:17
Topics
Non-DITA Purist
reference or often a starting point for
specialization
www.publishingsmarter.com29 9:18
According to DITA: topic
Top-level DITA element for a single subject or
article
Starting point for all other base topic types
Used if no other topic type applies
www.publishingsmarter.com30 9:18
DITA topic structure
Structure
title
shortdesc (or abstract)
prolog
body
sections and examples
block-levelelements
phrases and keywords
images and multimedia
related links
nested topics
TOPIC
6. 6
www.publishingsmarter.com31
Attributes
display-atts
scale, frame, expanse
id-atts
id, conref
select-atts
platform, product,
audience, otherprops,
importance, rev, status
topicref-atts
collection-type,type,
scope, locktitle, format,
linking, toc, print,
search, chunk
univ-atts
all select-atts, all id-atts,
translate, xml:lang
Control and Publish DITA
Beyond writing: Sharing, managing,
linking, and publishing topics
www.publishingsmarter.com33 9:07
Starting points beyond writing
conref: Content that is referenced or reused within
topcs
map: Doc with info about topic relationships as well
as optional links, groups, and navigation functions
reltable: Used to manage relationships between
topics (beyond parent/child) when used in a map
ditaval: Publishing or output information used
when converting DITA to print or online outputs
www.publishingsmarter.com34 9:23
According to DITA: conref
Reused content (content reference)
References to other content
A way to link to information and share it
across projects if needed
www.publishingsmarter.com35 9:24
Benefits of a conref
Create once
Use often
Update source, all are
updated to match
www.publishingsmarter.com36 9:20
Definition of a map
Describes relationships between resources
(such as DITA topics)
References to resources organized into
hierarchies and groups
A way to express relationships in a single
common format
7. 7
www.publishingsmarter.com37 9:20
Map structure
Structure
title
topicrefs (can be nested)
topicmeta (more topic info
when in a specific map)
topichead (for extra titles)
topicgroup (for organizing and
inheriting properties)
reltables (map level
navigation functions)
DITAMAP
www.publishingsmarter.com38 9:21
Definition of a reltable
Describes non-hierarchical relationships
between resources (such as DITA topics)
References resources in a table model (often
concept/task/reference)
Non-DITA Purist: A bit like manually building a
group of related topics in help, but better
www.publishingsmarter.com39 9:23
Benefit of a reltable
Plan content linking
Combine topics for
linking and navigation
Not stored in the topic
Can be map specific
Can be shared
www.publishingsmarter.com40 9:25
What is a ditaval?
Conditional processing profile
Identifies values to conditionally process for a
particular output, build, etc
Non-DITA Purist: Sort of like conditional
content, or using show/hide settings but
better
www.publishingsmarter.com41 9:27
How to develop a ditaval?
ID content with attributes
Create ditaval files, and use to publish
If publishing Windows XP only vs Windows 7 only
<val>
<prop action='exclude att='platform' val='Win7' ></prop>
</val>
or
<val>
<prop action='exclude' att='platform' val='XP'></ prop>
</val>
Visualize the Process
How might DITA work?
8. 8
www.publishingsmarter.com43 8:06
Plan a collection of topics
Assume the following:
Word processor
Users are newer writers
Experience level is
novice to general
Familiarity with
Windows and very basic
tasks assumed
Main topics may
include some/all:
Product Overview
Launch
Create
Import
Save / Save As
Close / Open
Delete
www.publishingsmarter.com44 8:06
Assign topic types
Take list of topics and assign types
Consider primary DITA ideas
Task
Concept
Reference
Some may have more than one topic type
www.publishingsmarter.com45 8:06
Develop a map
At a high level, decide on primary goal
Make that goal clear
Add supporting content
Maps as org charts
Manage
Files
C_Manage
T_Create
C_SaveAs
T_Save
T_SaveAs
R_Format
T_Close
T_Open
www.publishingsmarter.com46 8:06
Maps as a TOC
www.publishingsmarter.com47 8:06 www.publishingsmarter.com48 8:07
Maps for planning content
ManageFiles
C_Manage T_Create C_SaveAs
T_Save T_SaveAs
R_Formats T_Close T_Open
10. 10
www.publishingsmarter.com55 8:08
Map and relationships
ManageFiles
C_Manage T_Create C_SaveAs
T_Save T_SaveAs
R_Formats T_Close T_Open
www.publishingsmarter.com56 8:08
Map and relationships
ManageFiles
C_Manage T_Create C_SaveAs
T_Save T_SaveAs
R_Formats T_Close T_Open
www.publishingsmarter.com57 8:08
Map and relationships
ManageFiles
C_Manage T_Create C_SaveAs
T_Save T_SaveAs
R_Formats T_Close T_Open
www.publishingsmarter.com58 8:09
Map and relationships
ManageFiles
C_Manage T_Create C_SaveAs
T_Save T_SaveAs
R_Formats T_Close T_Open
www.publishingsmarter.com59 8:09
Map and relationships
ManageFiles
C_Manage T_Create C_SaveAs
T_Save T_SaveAs
R_Formats T_Close T_Open
www.publishingsmarter.com60 8:09
Relationship table sample
Reason/Note Task Concept Reference
Files that have been
created likely should be
saved
T_SaveAs
T_Save
T_Create
C_SaveAs
11. 11
www.publishingsmarter.com61 8:09
Relationship table sample
Reason/Note Task Concept Reference
Files that have been
created likely should be
saved
T_SaveAs
T_Save
T_Create
C_SaveAs
www.publishingsmarter.com62 8:10
Relationship table sample
Reason/Note Task Concept Reference
Files that have been
created likely should be
saved
T_SaveAs
T_Save
T_Create
C_SaveAs
www.publishingsmarter.com63 8:10
Reltable linking to concept
Reason/Note Task Concept Reference
Files that have been
created likely should be
saved
T_SaveAs
T_Save
T_Create
C_SaveAs R_Formats
www.publishingsmarter.com64 8:10
Title/shortdesc samples
Create documents (file: T_Create)
New electronic files can be produced as required.
Saving with a specific name (file: C_SaveAs)
Electronic files that have not yet been saved can
be saved to specific locations with specific
names; even files that have been previously
saved can be updated with a new name or
location.
File formats (file: R_Formats)
Many common types of documents can be
worked with.
www.publishingsmarter.com65 8:11
Title/shortdesc samples
Create documents (file: T_Create)
New electronic files can be produced as required.
Saving with a specific name (file: C_SaveAs)
Electronic files that have not yet been saved can
be saved to specific locations with specific
names; even files that have been previously
saved can be updated with a new name or
location.
File formats (file: R_Formats)
Many common types of documents can be
worked with.
www.publishingsmarter.com66 8:11
Automated prototypes (1/2)
12. 12
www.publishingsmarter.com67 8:11
Map and topics
ManageFiles
C_Manage T_Create C_SaveAs
T_Save T_SaveAs
R_Format T_Close T_Open
www.publishingsmarter.com68 8:11
Map and topics
ManageFiles
C_Manage T_Create C_SaveAs
T_Save R_Formats
T_SaveAs T_Close T_Open
www.publishingsmarter.com69 8:12
Title/shortdesc samples
Create documents (file: T_Create)
New electronic files can be produced as required.
Saving with a specific name (file: C_SaveAs)
Electronic files that have not yet been saved can
be saved to specific locations with specific
names; even files that have been previously
saved can be updated with a new name or
location.
File formats (file: R_Formats)
Many common types of documents can be
worked with.
www.publishingsmarter.com70 8:12
Automated prototypes (2/2)
www.publishingsmarter.com71 8:12
Automated prototypes (2/2)
www.publishingsmarter.com72 8:12
Attributes and output
ManageFiles
C_Manage T_Create C_SaveAs
T_Save R_Formats
T_SaveAs T_Close T_Open
13. 13
www.publishingsmarter.com73 8:12
Conditional inclusion/publish
ManageFiles
C_Manage T_Create C_SaveAs
T_Save R_Formats
T_SaveAs T_Close T_Open
T_Delete
(audience=admin)
Comparison of the TOC
www.publishingsmarter.com74 8:12
Core ideas within DITA
www.publishingsmarter.com75 8:59
Maps
Used to plan, organize, and
publish
Reltables
Build relationships between
info in maps
Topics
Types of info in a map, generally
as task, concept, or reference
Specializations
Customize as needed if other
options are exhausted
Contact Information
Contact Bernard
bernard@publishingsmarter.com
Call 905 833 8448
Twitter: aschwanden or aschwanden4stc
LinkedIn
www.publishingsmarter.com 9:06
www.publishingsmarter.com 9:06
Bonus Materials
If we are quick, then the following bonuses
Build a better mouse doc
ID the audience, the problems they want to
resolve
Build a map and reltable
Create content
Create many outputs
www.publishingsmarter.com 9:06
14. 14
Build a better mouse doc
And the world will beat a path to
your doc team
www.publishingsmarter.com80 9:28
Document planning
Imagine a publication that is very simple
Documentation for a remote mouse
It has basic or no documentation
A rough idea is suggested to management
An outline is created
Stub files and a map are drafted
www.publishingsmarter.com81 9:31
Document development
Topics are updated
Drafts are provided along the way for review
Very informal system early on
Can implement a CMS over time
www.publishingsmarter.com82 9:32
Who the user is
Mouse Tasks Performed (Generalize yes/no)
Audience Install/Config Use
IT Staff Yes
No
No
Presenter No Yes
No
www.publishingsmarter.com83 9:32
Our users: Doing/Seeking
Mouse Model of the User
Audience Install/Config Use
IT Staff Install it on a PC
Test the operations
Configure settings/speed
Wherecan I get a driver?
Presenter How do I run a presentation?
What functions are built in?
Will it function like a mouse?
Why are functions failing?
www.publishingsmarter.com84 9:33
Problems they may encounter
Mouse Problems faced when they need to
Audience Install/Config Use
IT Staff How long will it take
How much config is there
Will this OS support it
What if we lose the receiver?
Do I have to train users?
Presenter Dead batteries
Slideshow issues (advance,
build, blackout/whiteout)
Overlysensitive to the touch
15. 15
www.publishingsmarter.com85 9:34
List of topics (sample)
Topic Topic Topic
Computer requirements Adjust remote sensitivity How to order
Shipping cost, product cost,
warrantycosts
Drivers (OS specific) Installation
First time use Regular use Test the install
Double click speed Scroll speed Button functions
Run a slideshow Troubleshooting
Replace the batteries Slideshow tips and tricks Components
Connect the mouse to a PC
www.publishingsmarter.com86 9:34
List of topics with type (sample)
Topic and type Topic and type Topic and type
R_SystemRequirements T_TouchSensitivity, (and C_) T_OrderNow
R_Costs (shipping, product,
warrantyextension)
R_DriversAndDownloads T_Install
T_FirstTimeUse, (maybe C_) T_NormalUse T_InstallTest
T_AdjustDoubleClickSpeed T_AdjustScrollSpeed R_ButtonFunctions
T_RunSlideShow R_Troubleshooting R_SupportedOS
T_ChangeBatteries R_SlideshowTips R_Components
T_Connect
www.publishingsmarter.com87 9:37
Presenter Map (sample)
T_NormalUse
T_Connect
C_FirstTimeUse
T_ChangeBatteries
R_Components
T_FirstTimeUse
T_NormalUse (cont)
T_RunSlideShow
R_SlideShowTips
R_ButtonFunctions
R_Troubleshooting
T_AdjustDoubleClick
T_TouchSensitivity
www.publishingsmarter.com88 9:38
Distribution of content
In the map there are 12 topics
7 are tasks
1 is a concept
4 are reference
www.publishingsmarter.com89 9:39
Develop reltables (sample)
Keep it simple, easy to understand
Focus on tasks early on
Notes Task Concept Reference
People may look up
tips to find out what a
button does, or refer
to it during a
presentation
T_RunSlideShow R_ButtonFunctions
R_SlideShowTIps
R_ButtonFunctions
Sometimes when
connecting the
batteries are dead
T_ChangeBatteries R_Troubleshooting
www.publishingsmarter.com90 9:39
Initial title/file/shortdesc
Title/File Shortdesc
Regular mouse use
(T_NormalUse)
Your day to day use of the mouse may include common tasks like scrolling and
clicking, presenting slide shows, or using it as a laser pointer.
Connect the mouse
(T_Connect)
Before you use the device, connect the receiver to your computer and ensure the
connection is active.
Change batteries
(T_ChangeBatteries)
When you first set up the device, or if connecting and a signal is not being sent,
new batteries may have to be inserted.
Parts of the device
(R_Components)
Two primary components of the device are detailed.
Using the remote
mouse for the first
time (C_FirstTimeUse)
The remote mouse has to be set up by following an initial installation process the
first time it is used, and we recommend general familiarity with core ideas before
starting.
Initial steps for new
users (T_FirstTimeUse)
When you work with the device as a first time user there are a few core things you
need to do to ensure your product works as intended.
16. 16
www.publishingsmarter.com91 9:39
Initial title/file/shortdesc
Title/File Shortdesc
Present a slideshow
(T_RunSlideShow)
PowerPoint presentations (and other slide show formats) can be run using the
device as a mobile mouse allowing you to walk around while presenting.
Tips on running slide
shows
(R_SlideShowTips)
The functions of specific buttons change their specific functions when running a
slideshow.
Device button
functions
(R_ButtonFunctions)
The functions of specific buttons allow scrolling, primary and secondary mouse
clicks, and specific functions within different applications.
Troubleshooting
(R_Troubleshooting)
The device should function as expected, but if it does not, troubleshooting
information is available to self-test before contacting our technical support.
Change double click
speed
(T_AdjustDoubleClick)
If you find that the delay between two clicks is too fast, or not fast enough, you can
adjust it to your personal preferences.
Change pointer speed
(T_TouchSensitivity)
If you find that the device scrolls too fast, or not fast enough, you can adjust it to
your personal preferences.
www.publishingsmarter.com92 9:40
Now write
Begin with tasks
Identify any prerequisite as soon as possible
Identify the benefit of doing this
Write clear tasks
Each step is self contained
A step has a basic command
Early steps have a result (to let the user know he is on
the right path)
Add concept/reference as needed
www.publishingsmarter.com93 10:13
Continue to write/update
