The document discusses the complexity of DITA (Darwin Information Typing Architecture). It explores both objective and subjective measures of complexity, including the number of parts and connections in a system. While DITA has many tags and features that could make it complex, the document argues that complexity depends on an individual's background and needs, and it can be managed by reducing specializations, using tools, and clearly defining roles. The speaker seeks audience input on how complex different DITA features seem and whether any parts seem too difficult.

1. Is DITA Simple, Complex, or Too
@jimtvanc #LavaCon
Complex?
Jim Tivy

2. @jimtvanc #LavaCon
About the speaker
• Documentation systems since the 80s
• Entity modeling, database system specialist
• XQuery Working Group early 2000s
• CTO, Bluestream
• Member, Oasis DITA TC

3. Overview
• Why do we care
• What is complexity
• DITA complexity
• How to manage complexity
• Is DITA simple, complex, or too complex
@jimtvanc #LavaCon

4. Why do we care?
• ROI
• We want to get the work done
• Change management
– Answer to “This is too complex”
• Should we be pursuing alternatives
@jimtvanc #LavaCon

5. What is complexity?
• Complexus – entwined
• A system would be more complex if more
parts could be distinguished and if more
connections between them existed
(Principia)
• Classes of Individuals and Relationships
between such individuals
• Value and state spaces
@jimtvanc #LavaCon

6. sodium chloride crystal
@jimtvanc #LavaCon
classic example of ionic bonds

7. Objective and subjective
• Objective
– Number of parts
– Number of connections
– Size of state space
• Subjective
– Different backgrounds
– Different ways of storing knowledge
– Energy
@jimtvanc #LavaCon

8. Knowledge
“facts, information, and skills acquired by
a person through experience or
education; the theoretical or practical
understanding of a subject”
(Google)
@jimtvanc #LavaCon

9. DITA complexity
• Check the “story” …
• Look for “external subject references”
• Look for “unnecessary information”
@jimtvanc #LavaCon

10. Structured writing
• Information types of concept, task,
reference (Robert E Horn)
• Structure not presentation
– ignoring <b> and <i>
– semantic tagging – e.g.: <step> not <li>
• Chunks of content – topics
• “Address problems in complex writing”
@jimtvanc #LavaCon

11. Topics
• “Basic unit of authoring and re-use”
• “Can be generic or more specialized”
• “Content units in DITA are expressed
using XML elements and can be
conditionally processed using metadata
attributes and values”
• Elements, attributes – time to learn XML
@jimtvanc #LavaCon

12. The rabbit hole
• To be researched
• XML is ordered
• However, expansive
• “In another moment down went Alice after
it, never once considering how in the world
she was to get out again”
• Keep your eye on the ball
@jimtvanc #LavaCon

13. XML concepts
• Extensible Markup Language
• XML document – unfortunate terminology
• “XML documents are made up of storage
units called entities, which contain either
parsed or unparsed data” (Introduction)
• Beam me up…
@jimtvanc #LavaCon

14. XML - tag view
@jimtvanc #LavaCon
start
element
end
element

15. XML – tree view
@jimtvanc #LavaCon

16. XML – text view
@jimtvanc #LavaCon
Document
Type
Attribute

17. Word-like view
@jimtvanc #LavaCon

18. XML in summary
• XML is a way to structure content in
documents. XML structures using a tree
of elements which enclose content tagging
that content with a meaningful name.
• Tags are processed by computers, for
example: to render the document to a PDF
or HTML publication.
@jimtvanc #LavaCon

19. Topics – conditional text
• Now we know XML
• <li product="bluetooth>Talk using a
Bluetooth wireless headset</li>
• <val>
<prop action="exclude" att="product“
val="bluetooth"/>
</val>
@jimtvanc #LavaCon

20. Transclusion
• <p><ph
conref="/Content/ReUse.xml#ReUseId/Copyright"/>
</p>
• <ph id="Copyright">© Copyright 2009 - 2013. All rights
reserved.</ph>
• push, pull, conkeyref
@jimtvanc #LavaCon

21. Linking
• <image href="/Content/Generic-phone.jpg"/>
• See: <xref href="Listen_to_music.xml#task_listen"/>
• <related-links>
<link
href="Listen_to_music.xml#task_listen"/>
</related-links>
@jimtvanc #LavaCon

22. Relationship table
<reltable><relheader>
<relcolspec linking="normal"/>
<relcolspec linking="normal"/>
</relheader>
<relrow>
<relcell collection-type="family">
<topicref href="/Content/Getting_Started.xml"
</relcell>
<relcell collection-type="family">
<topicref href="/Content/Make_calls.xml"/>
<topicref href="/Content/Listen_to_music.xml"/>
<topicref href="/Content/Take_photos.xml”/>
</relcell>
</relrow>
</reltable>
@jimtvanc #LavaCon

23. DITA maps
• Reference all topics in publication
• Define hierarchy of topics
• Define the context in which topics are
processed
• (Maps) “can be used by information
architects, writers, and publishers to plan,
develop, and deliver content”
@jimtvanc #LavaCon

24. Processors
• Publishing processor – e.g. DITA OT
• Editors
• CMS UX
• DITA XML documents are computer
readable and “typed”
• Processors can use implied class attribute
<title class="- topic/title ">Nav…</title>
@jimtvanc #LavaCon

25. Map context
• Key definitions
<keydef keys="Product_Name" processing-role="
resource-only">
<topicmeta>
<keywords>
<keyword>Basic Phone</keyword>
</keywords>
</topicmeta>
</keydef>
@jimtvanc #LavaCon

26. Key references
• Key references
<title>Getting Started with your <keyword
keyref="Product_Name"/></title>
@jimtvanc #LavaCon

27. <glossref>
• <p>Your <term keyref="voice_mail"/> must… </p>
• <map>
<topicref href="/Content/Retrieve_voicemail.xml"/>
...
<topichead navtitle="Glossary>
<glossref href="/Content/VoiceMail.xml“
keys="voice_mail“
linking="normal" toc="no" print="yes"/>
...
</topichead>
</map>
@jimtvanc #LavaCon

28. Objective
• Approximately 800 tags
• Sophisticated features
• System of systems
• Add on systems like a CMS
• Not to mention
– Specialization
– DITA 1.3 - Key scopes, branch filtering
• = complex
@jimtvanc #LavaCon

29. Subjective
• Which is simple, complex, too complex?
1. Conditional processing
2. Transclusion
3. Linking
4. Relationship tables
5. Maps
6. Keys
7. Glossref
• Is XML simple, complex, too complex?
@jimtvanc #LavaCon

30. Managing complexity
• Which roles have to know what
– Author
– SME
– Publisher
– Localizer
• Reduce specializations and domains
• Tool abstractions and helpers
• Tool demo
@jimtvanc #LavaCon

31. Too complex
• ROI – your requirements and features
• Could it be simpler?
• Future promise
• Resonance – e.g. HTML, SVG, Linking
• Alternatives
– Lightweight DITA
– Flare, Confluence
@jimtvanc #LavaCon

32. Your thoughts
Degree of Complexity for an Author
1. Simple
2. Some parts are complex
3. Many parts are complex
4. Most parts are complex
5. Too complex
@jimtvanc #LavaCon