This presentation is copyrighted - © JANG Communication 2010
DITA for Dummies®
An introduction to
the core concepts of DITA
“for the Rest of Us!®”
Jang F.M. Graat
JANG Communication
Amsterdam
All items marked with ® are registered trademarks of Wiley Publishing, Inc.
zaterdag 6 november 2010
1
This presentation is copyrighted - © JANG Communication 2010
DITA core concepts
1. Structure
2. Minimalism
3. Specialization
4. Conrefs
5. Constraints
®
zaterdag 6 november 2010
2
This presentation is copyrighted - © JANG Communication 2010
1. Structure
struc-tured, adj. having and manifesting a clearly
defined structure or organization.
Webster’s Encyclopedic Unabridged Dictionary of the English Language, 1996
zaterdag 6 november 2010
3
This presentation is copyrighted - © JANG Communication 2010
Structure makes our lives easier
zaterdag 6 november 2010
4
This presentation is copyrighted - © JANG Communication 2010
How to structure information ?
zaterdag 6 november 2010
5
This presentation is copyrighted - © JANG Communication 2010
Visible cues used consistently
zaterdag 6 november 2010
6
This presentation is copyrighted - © JANG Communication 2010
<h1>DITA for Dummies</h1>
<p>An introduction to the core concepts of DITA</p>
<h2>&quot;For the Rest of Us!&reg;&quot;</h2>
<h3>Jang F.M. Graat</h3>
<p>JANG Communication<br>Amsterdam</p>
Markup languages: content plus markup labels
zaterdag 6 november 2010
7
This presentation is copyrighted - © JANG Communication 2010
<title>DITA for Dummies</title>
<subtitle>An introduction to the core concepts of DITA</subtitle>
<byline>
<trademark>For the Rest of Us!</trademark>
</byline>
<author>
<name>
<first>Jang</first>
<middle>F.M.</niddle>
<last>Graat</last>
</name>
<company>JANG Communication</company>
<location>Amsterdam</location>
</author>
XML enables using semantic labels
zaterdag 6 november 2010
8
This presentation is copyrighted - © JANG Communication 2010
XML is eXtensible - create your own structuring method
zaterdag 6 november 2010
9
This presentation is copyrighted - © JANG Communication 2010
XML is eXtensible - but which extension is sensible ?
zaterdag 6 november 2010
10
This presentation is copyrighted - © JANG Communication 2010
DITA - an XML standard for modular documentation
zaterdag 6 november 2010
11
This presentation is copyrighted - © JANG Communication 2010
2. Minimalism
min-i-mal, adj. barely adequate or the least possible
Webster’s Encyclopedic Unabridged Dictionary of the English Language, 1996
zaterdag 6 november 2010
12
This presentation is copyrighted - © JANG Communication 2010
It can do almost anything, but you’re hopeless with it
zaterdag 6 november 2010
13
This presentation is copyrighted - © JANG Communication 2010
It only does one thing, and does that one thing very well
zaterdag 6 november 2010
14
This presentation is copyrighted - © JANG Communication 2010
John M. Carroll - books on minimalism 1990, 1998
zaterdag 6 november 2010
15
This presentation is copyrighted - © JANG Communication 2010
Users do not want more information
zaterdag 6 november 2010
16
This presentation is copyrighted - © JANG Communication 2010
One question
• How do I do this ?
• What went wrong ?
• What are my options ?
• What is this thing for ?
• How does this work ?
zaterdag 6 november 2010
17
This presentation is copyrighted - © JANG Communication 2010
Authors do not need more options
zaterdag 6 november 2010
18
This presentation is copyrighted - © JANG Communication 2010
topics
maps
docs
Minimalism requires + enables modularity
zaterdag 6 november 2010
19
This presentation is copyrighted - © JANG Communication 2010
3. Specialization
spe-cial-ize, v. to adapt to special conditions; restrict to
specific limits.
Webster’s Encyclopedic Unabridged Dictionary of the English Language, 1996
zaterdag 6 november 2010
20
This presentation is copyrighted - © JANG Communication 2010
One size does not fit all - if it did, we would all be fish
zaterdag 6 november 2010
21
This presentation is copyrighted - © JANG Communication 2010
Usability is always related to a specific environment
zaterdag 6 november 2010
22
This presentation is copyrighted - © JANG Communication 2010
Specialization and inheritance (the Darwin part of DITA)
zaterdag 6 november 2010
23
This presentation is copyrighted - © JANG Communication 2010
topic
@
id, conref
title
titlealts
shortdesc
abstract
prolog
body
related-links
p
lq
note
ul
ol
sl
pre
lines
fig
image
object
topic
Basic topic
zaterdag 6 november 2010
24
This presentation is copyrighted - © JANG Communication 2010
task
@
id, conref
title
titlealts
shortdesc
abstract
prolog
taskbody
prelreqs
context
section
steps
steps-unordered
steps-informal
related-links
task
result
example
closereqs
Structural specialization : machinery task
zaterdag 6 november 2010
25
This presentation is copyrighted - © JANG Communication 2010
topic
@
id, conref
title
titlealts
shortdesc
abstract
prolog
body
related-links
topic
dl
parml
fig
syntaxdiagram
imagemap
image
lines
lq
note
hazardstatement
object
ol
p
pre
codeblock
msgblock
screen
simpletable
sl
table
ul
data
data-about
draft-comment
foreign
unknown
required-cleanup
conbodydiv
example
section
Domain specialization : elements from various domains
zaterdag 6 november 2010
26
This presentation is copyrighted - © JANG Communication 2010
Basic type : room
zaterdag 6 november 2010
27
This presentation is copyrighted - © JANG Communication 2010
Structural specialization : bedroom
zaterdag 6 november 2010
28
This presentation is copyrighted - © JANG Communication 2010
Structural specialization : dining room
zaterdag 6 november 2010
29
This presentation is copyrighted - © JANG Communication 2010
Domain specialization: hotel rooms
zaterdag 6 november 2010
30
This presentation is copyrighted - © JANG Communication 2010
Domain specialization: hospital rooms
zaterdag 6 november 2010
31
This presentation is copyrighted - © JANG Communication 2010
Structural
Domains
Concept
Programming elements
Reference
Software elements
Task
User interface elements
Machinery task
Task requirements elements
Glossary entry
xNAL - elements
Glossary group
Abbreviated form element
Bookmap
Glossary reference element
Learning and Training specialization
Standard specializations in DITA 1.2
zaterdag 6 november 2010
32
This presentation is copyrighted - © JANG Communication 2010
4. Conrefs
In computer science, transclusion is the inclusion of a
document or part of a document into another document
by reference.
Wikipedia
zaterdag 6 november 2010
33
This presentation is copyrighted - © JANG Communication 2010
Copying content : not the most economic option
zaterdag 6 november 2010
34
This presentation is copyrighted - © JANG Communication 2010
Copy-paste is expensive and leads to inconsistencies
zaterdag 6 november 2010
35
This presentation is copyrighted - © JANG Communication 2010
Referencing content : not the most user-friendly option
zaterdag 6 november 2010
36
This presentation is copyrighted - © JANG Communication 2010
proc1
proc1
Replacing the drive
Replacing the drive
Procedure:
1. Remove the cover
2. Remove the drive
3. Disconnect the cables
4. Mount the new drive
5. Connect the cables
6. Mount the cover
proc2
corrections
pub1
Procedure:
1. Open the cover
2. Remove the drive
3. Disconnect the cables
4. Mount the new drive
5. Connect the cables
6. Close the cover
pub2
Replacing the bearings
Replacing the bearings
Replacing the bearings
Procedure:
1. <include “proc1_step1”>
2. <include “proc1_step2”>
3. Remove the ball bearings
4. Mount new ball bearings
5. Apply grease
6. <include “proc1_step4”>
7. <include “proc1_step6”>
Procedure:
1. Remove the cover
2. Remove the drive
3. Remove the ball bearings
4. Mount new ball bearings
5. Apply grease
6. Mount the new drive
7. Mount the cover
Procedure:
1. Open the cover
2. Remove the drive
3. Remove the ball bearings
4. Mount new ball bearings
5. Apply grease
6. Mount the new drive
7. Close the cover
Write-time references, read-time copies
zaterdag 6 november 2010
37
This presentation is copyrighted - © JANG Communication 2010
Authors ‘borrow’ existing content
zaterdag 6 november 2010
38
This presentation is copyrighted - © JANG Communication 2010
Link to any element in any DITA file
zaterdag 6 november 2010
39
This presentation is copyrighted - © JANG Communication 2010
Conrefs are checked for consistency
zaterdag 6 november 2010
40
This presentation is copyrighted - © JANG Communication 2010
5. Constraints
con-straint, n. repression of natural feelings and
impulses
Webster’s Encyclopedic Unabridged Dictionary of the English Language, 1996
zaterdag 6 november 2010
41
This presentation is copyrighted - © JANG Communication 2010
Writing for users
• Only required info
• One answer per topic
• Always same structure
• As boring as possible
• Become a minimalist
Define a more restrictive selection and order of elements
zaterdag 6 november 2010
42
This presentation is copyrighted - © JANG Communication 2010
Without constraints, there is chaos
zaterdag 6 november 2010
43
This presentation is copyrighted - © JANG Communication 2010
Rule #1: limitations
zaterdag 6 november 2010
44
This presentation is copyrighted - © JANG Communication 2010
Rule #2: limitations
zaterdag 6 november 2010
45
This presentation is copyrighted - © JANG Communication 2010
Rule #3: limitations
zaterdag 6 november 2010
46
This presentation is copyrighted - © JANG Communication 2010
Specialization is endless
zaterdag 6 november 2010
47
This presentation is copyrighted - © JANG Communication 2010
All of DITA gives too many options
zaterdag 6 november 2010
48
This presentation is copyrighted - © JANG Communication 2010
Filter out elements that are not required
zaterdag 6 november 2010
49
This presentation is copyrighted - © JANG Communication 2010
Define required elements
zaterdag 6 november 2010
50
This presentation is copyrighted - © JANG Communication 2010
Define the structure of your topics
zaterdag 6 november 2010
51
This presentation is copyrighted - © JANG Communication 2010
task
@
id, conref
task
title
x
!
shortdesc
x
prolog
abstract
prolog
!
taskbody
related-links
1
!
x
x
!
prelreqs
steps
x
task
id, conref
title
titlealts
shortdesc
@
1
x
context
steps-unordered
x
x
section
taskbody
prelreqs
related-links
context
steps
steps-informal
closereqs
result
example
closereqs
Less than the full standard
zaterdag 6 november 2010
52
This presentation is copyrighted - © JANG Communication 2010
Constraints are defined in “mod” files
zaterdag 6 november 2010
53
This presentation is copyrighted - © JANG Communication 2010
Carry only what you need for the job
zaterdag 6 november 2010
54
This presentation is copyrighted - © JANG Communication 2010
A perfect fit for every occasion
zaterdag 6 november 2010
55
This presentation is copyrighted - © JANG Communication 2010
Questions ?
Jang F.M. Graat
JANG Communication
Amsterdam
[email protected]
zaterdag 6 november 2010
56