Dita 4 Dummies

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


DITA core concepts

1. Structure

2. Minimalism

3. Specialization

4. Conrefs

5. Constraints
®



1. Structure
struc-tured, adj. having and manifesting a clearly
deﬁned structure or organization.

Webster’s Encyclopedic Unabridged Dictionary of the English Language, 1996



Structure makes our lives easier


How to structure information ?


Visible cues used consistently


<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


<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


XML is eXtensible - create your own structuring method


XML is eXtensible - but which extension is sensible ?


DITA - an XML standard for modular documentation


2. Minimalism
min-i-mal, adj. barely adequate or the least possible




It can do almost anything, but you’re hopeless with it


It only does one thing, and does that one thing very well


John M. Carroll - books on minimalism 1990, 1998


Users do not want more information


One question

• How do I do this ?

• What went wrong ?

• What are my options ?

• What is this thing for ?

• How does this work ?



Authors do not need more options


topics maps docs

Minimalism requires + enables modularity


3. Specialization
spe-cial-ize, v. to adapt to special conditions; restrict to
speciﬁc limits.




One size does not ﬁt all - if it did, we would all be ﬁsh


Usability is always related to a speciﬁc environment


Specialization and inheritance (the Darwin part of DITA)


@
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


@
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


@
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


Basic type : room


Structural specialization : bedroom


Structural specialization : dining room


Domain specialization: hotel rooms


Domain specialization: hospital rooms


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


4. Conrefs
In computer science, transclusion is the inclusion of a
document or part of a document into another document
by reference.

Wikipedia



Copying content : not the most economic option


Copy-paste is expensive and leads to inconsistencies


Referencing content : not the most user-friendly option


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


Authors ‘borrow’ existing content


Link to any element in any DITA ﬁle


Conrefs are checked for consistency


5. Constraints
con-straint, n. repression of natural feelings and
impulses




Writing for users

• Only required info

• One answer per topic

• Always same structure

• As boring as possible

• Become a minimalist

Deﬁne a more restrictive selection and order of elements


Without constraints, there is chaos


Rule #1: limitations


Specialization is endless


All of DITA gives too many options


Filter out elements that are not required


Deﬁne required elements


Deﬁne the structure of your topics


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


Constraints are deﬁned in “mod” ﬁles


Carry only what you need for the job


A perfect ﬁt for every occasion


Questions ?

Jang F.M. Graat
JANG Communication
Amsterdam

jang@jang.nl


Dita 4 Dummies

Recommandé

Recommandé

Contenu connexe

Tendances

Tendances (20)

Plus de Jang F.M. Graat

Plus de Jang F.M. Graat (20)

Dernier

Dernier (20)

Dita 4 Dummies