dita for dummies - tekom · 1. structure struc-tured, adj. having and manifesting a clearly...

An introduction to the core concepts of DITA

“for the Rest of Us!®”

DITA for Dummies®

Jang F.M. GraatJANG CommunicationAmsterdam

All items marked with ® are registered trademarks of Wiley Publishing, Inc.

This presentation is copyrighted - © JANG Communication 2010

1zaterdag 6 november 2010

DITA core concepts

1. Structure

2. Minimalism

3. Specialization

4. Conrefs

5. Constraints

®



1. Structurestruc-tured, adj. having and manifesting a clearly defined 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



Markup languages: content plus markup labels

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



XML enables using semantic 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 is eXtensible - create your own structuring method



XML is eXtensible - but which extension is sensible ?



DITA - an XML standard for modular documentation



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



• How do I do this ?

• What went wrong ?

• What are my options ?

• What is this thing for ?

• How does this work ?

One question



Authors do not need more options



Minimalism requires + enables modularity

topics maps docs



spe-cial-ize, v. to adapt to special conditions; restrict to specific limits.


3. Specialization



One size does not fit all - if it did, we would all be fish



Usability is always related to a specific environment



Specialization and inheritance (the Darwin part of DITA)



Basic topic

titlealts

topic

title

id, conref@

prolog

body

related-links

topic

lq note

ol

p

image

pre

fig

lines

object

sl

ul

abstractshortdesc



Structural specialization : machinery task

titlealts

task

title

id, conref@

abstractshortdesc

prolog

taskbody

related-links

task

prelreqs

steps

context

steps-unordered

section

steps-informal

result

example

closereqs



Domain specialization : elements from various domains

titlealts

topic

title

id, conref@

abstractshortdesc

prolog

body

related-links

topic

dl syntaxdiagram

imagemap lq

note ol

p

parml

image

hazardstatement

pre

fig

lines

object

codeblock msgblock

screen simpletable sl table

ul data data-about

foreign unknown

example

draft-comment

conbodydiv

section

required-cleanup



Basic type : room



Structural specialization : bedroom



Structural specialization : dining room



Domain specialization: hotel rooms



Domain specialization: hospital rooms



Standard specializations in DITA 1.2

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



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



Write-time references, read-time copies

Replacing the bearings

Procedure:1. <include “proc1_step1”>2. <include “proc1_step2”>3. Remove the ball bearings4. Mount new ball bearings5. Apply grease6. <include “proc1_step4”>7. <include “proc1_step6”>

Replacing the drive

Procedure:1. Remove the cover2. Remove the drive3. Disconnect the cables4. Mount the new drive5. Connect the cables6. Mount the cover

proc2

proc1

Replacing the bearings

Procedure:1. Remove the cover2. Remove the drive3. Remove the ball bearings4. Mount new ball bearings5. Apply grease6. Mount the new drive7. Mount the cover

Replacing the drive

Procedure:1. Open the cover2. Remove the drive3. Disconnect the cables4. Mount the new drive5. Connect the cables6. Close the cover

proc1

pub1Replacing the bearings

Procedure:1. Open the cover2. Remove the drive3. Remove the ball bearings4. Mount new ball bearings5. Apply grease6. Mount the new drive7. Close the cover

pub2

corrections



Authors ‘borrow’ existing content



Link to any element in any DITA file



Conrefs are checked for consistency



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




• Only required info

• One answer per topic

• Always same structure

• As boring as possible

• Become a minimalist

Writing for users

Define 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



Define required elements



Define the structure of your topics



Less than the full standard

titlealts

task

title

id, conref@

abstractshortdesc

prolog

taskbody

related-links

task

prelreqs

steps

context

steps-unordered

section

steps-informal

result

example

closereqs

x!x

xx

xx

!

!! 1

x

1 x

task

title

id, conref@

shortdesc

prolog

taskbody

related-links

prelreqs

steps

context

closereqs



Constraints are defined in “mod” files



Carry only what you need for the job



A perfect fit for every occasion



Questions ?

Jang F.M. Graat

JANG CommunicationAmsterdam

[email protected]



dita for dummies - tekom · 1. structure struc-tured, adj. having and manifesting a clearly...

Documents