Mais conteúdo relacionado Mais de Jang F.M. Graat (20) Dita 4 Dummies1. 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>"For the Rest of Us!®"</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