From the start of my career, I have tried to explain technology to people who may be less trained in it than most of the geeks who run around trying to sell their stuff. With DITA, the concepts can be explained by relating them to real-world examples. This presentation was done at DITA North America in San Jose and tcworld in Wiesbaden.

1. 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

2. 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

3. 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

4. This presentation is copyrighted - © JANG Communication 2010
Structure makes our lives easier
zaterdag 6 november 2010 4

5. This presentation is copyrighted - © JANG Communication 2010
How to structure information ?
zaterdag 6 november 2010 5

6. This presentation is copyrighted - © JANG Communication 2010
Visible cues used consistently
zaterdag 6 november 2010 6

7. 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

8. 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

9. This presentation is copyrighted - © JANG Communication 2010
XML is eXtensible - create your own structuring method
zaterdag 6 november 2010 9

10. This presentation is copyrighted - © JANG Communication 2010
XML is eXtensible - but which extension is sensible ?
zaterdag 6 november 2010 10

11. This presentation is copyrighted - © JANG Communication 2010
DITA - an XML standard for modular documentation
zaterdag 6 november 2010 11

12. 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

13. This presentation is copyrighted - © JANG Communication 2010
It can do almost anything, but you’re hopeless with it
zaterdag 6 november 2010 13

14. This presentation is copyrighted - © JANG Communication 2010
It only does one thing, and does that one thing very well
zaterdag 6 november 2010 14

15. This presentation is copyrighted - © JANG Communication 2010
John M. Carroll - books on minimalism 1990, 1998
zaterdag 6 november 2010 15

16. This presentation is copyrighted - © JANG Communication 2010
Users do not want more information
zaterdag 6 november 2010 16

17. 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

18. This presentation is copyrighted - © JANG Communication 2010
Authors do not need more options
zaterdag 6 november 2010 18

19. This presentation is copyrighted - © JANG Communication 2010
topics maps docs
Minimalism requires + enables modularity
zaterdag 6 november 2010 19

20. 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

21. 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

22. This presentation is copyrighted - © JANG Communication 2010
Usability is always related to a specific environment
zaterdag 6 november 2010 22

23. This presentation is copyrighted - © JANG Communication 2010
Specialization and inheritance (the Darwin part of DITA)
zaterdag 6 november 2010 23

24. This presentation is copyrighted - © JANG Communication 2010
@
topic id, conref
title
titlealts
shortdesc abstract
prolog
body p lq note ul
ol sl pre lines
related-links
fig image object
topic
Basic topic
zaterdag 6 november 2010 24

25. This presentation is copyrighted - © JANG Communication 2010
@
task id, conref
title
titlealts
shortdesc abstract
prolog
taskbody prelreqs context section
related-links
steps steps-unordered steps-informal
task
result
example
closereqs
Structural specialization : machinery task
zaterdag 6 november 2010 25

26. This presentation is copyrighted - © JANG Communication 2010
@
topic id, conref
title
titlealts
shortdesc abstract
prolog
body dl parml fig syntaxdiagram
imagemap image lines lq
related-links
note hazardstatement object ol
topic
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

27. This presentation is copyrighted - © JANG Communication 2010
Basic type : room
zaterdag 6 november 2010 27

28. This presentation is copyrighted - © JANG Communication 2010
Structural specialization : bedroom
zaterdag 6 november 2010 28

29. This presentation is copyrighted - © JANG Communication 2010
Structural specialization : dining room
zaterdag 6 november 2010 29

30. This presentation is copyrighted - © JANG Communication 2010
Domain specialization: hotel rooms
zaterdag 6 november 2010 30

31. This presentation is copyrighted - © JANG Communication 2010
Domain specialization: hospital rooms
zaterdag 6 november 2010 31

32. 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

33. 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

34. This presentation is copyrighted - © JANG Communication 2010
Copying content : not the most economic option
zaterdag 6 november 2010 34

35. This presentation is copyrighted - © JANG Communication 2010
Copy-paste is expensive and leads to inconsistencies
zaterdag 6 november 2010 35

36. This presentation is copyrighted - © JANG Communication 2010
Referencing content : not the most user-friendly option
zaterdag 6 november 2010 36

37. This presentation is copyrighted - © JANG Communication 2010
proc1 proc1
Replacing the drive Replacing the drive
Procedure: Procedure:
1. Remove the cover corrections 1. Open the cover
2. Remove the drive 2. Remove the drive
3. Disconnect the cables 3. Disconnect the cables
4. Mount the new drive 4. Mount the new drive
5. Connect the cables 5. Connect the cables
6. Mount the cover 6. Close the cover
proc2 pub1 pub2
Replacing the bearings Replacing the bearings Replacing the bearings
Procedure: Procedure: Procedure:
1. <include “proc1_step1”> 1. Remove the cover 1. Open the cover
2. <include “proc1_step2”> 2. Remove the drive 2. Remove the drive
3. Remove the ball bearings 3. Remove the ball bearings 3. Remove the ball bearings
4. Mount new ball bearings 4. Mount new ball bearings 4. Mount new ball bearings
5. Apply grease 5. Apply grease 5. Apply grease
6. <include “proc1_step4”> 6. Mount the new drive 6. Mount the new drive
7. <include “proc1_step6”> 7. Mount the cover 7. Close the cover
Write-time references, read-time copies
zaterdag 6 november 2010 37

38. This presentation is copyrighted - © JANG Communication 2010
Authors ‘borrow’ existing content
zaterdag 6 november 2010 38

39. This presentation is copyrighted - © JANG Communication 2010
Link to any element in any DITA file
zaterdag 6 november 2010 39

40. This presentation is copyrighted - © JANG Communication 2010
Conrefs are checked for consistency
zaterdag 6 november 2010 40

41. 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

42. 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

43. This presentation is copyrighted - © JANG Communication 2010
Without constraints, there is chaos
zaterdag 6 november 2010 43

44. This presentation is copyrighted - © JANG Communication 2010
Rule #1: limitations
zaterdag 6 november 2010 44

45. This presentation is copyrighted - © JANG Communication 2010
Rule #2: limitations
zaterdag 6 november 2010 45

46. This presentation is copyrighted - © JANG Communication 2010
Rule #3: limitations
zaterdag 6 november 2010 46

47. This presentation is copyrighted - © JANG Communication 2010
Specialization is endless
zaterdag 6 november 2010 47

48. This presentation is copyrighted - © JANG Communication 2010
All of DITA gives too many options
zaterdag 6 november 2010 48

49. This presentation is copyrighted - © JANG Communication 2010
Filter out elements that are not required
zaterdag 6 november 2010 49

50. This presentation is copyrighted - © JANG Communication 2010
Define required elements
zaterdag 6 november 2010 50

51. This presentation is copyrighted - © JANG Communication 2010
Define the structure of your topics
zaterdag 6 november 2010 51

52. This presentation is copyrighted - © JANG Communication 2010
@ @
task id, conref task id, conref
title title
x
titlealts shortdesc
!
shortdesc
x
abstract prolog
taskbody prelreqs
prolog
!
taskbody
1
prelreqs
1
context
x
section
related-links context
x x
steps
!
related-links
steps steps-unordered steps-informal
x
closereqs
task
x
result
x
example
!
closereqs
Less than the full standard
zaterdag 6 november 2010 52

53. This presentation is copyrighted - © JANG Communication 2010
Constraints are defined in “mod” files
zaterdag 6 november 2010 53

54. This presentation is copyrighted - © JANG Communication 2010
Carry only what you need for the job
zaterdag 6 november 2010 54

55. This presentation is copyrighted - © JANG Communication 2010
A perfect fit for every occasion
zaterdag 6 november 2010 55

56. This presentation is copyrighted - © JANG Communication 2010
Questions ?
Jang F.M. Graat
JANG Communication
Amsterdam
jang@jang.nl
zaterdag 6 november 2010 56