Embed Size (px)
DESCRIPTION
Is DITA Simple, Complex or Too Complex
Citation preview
@jimtvanc #LavaCon
Is DITA Simple, Complex, or Too Complex?
Jim Tivy
@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
Overview
• Why do we care
• What is complexity
• DITA complexity
• How to manage complexity
• Is DITA simple, complex, or too complex
@jimtvanc #LavaCon
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
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
sodium chloride crystal
@jimtvanc #LavaCon
classic example of ionic bonds
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
Knowledge
“facts, information, and skills acquired by a person through experience or education; the theoretical or practical understanding of a subject”
(Google)
@jimtvanc #LavaCon
DITA complexity
• Check the “story” …
• Look for “external subject references”
• Look for “unnecessary information”
@jimtvanc #LavaCon
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
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
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
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
XML - tag view
@jimtvanc #LavaCon
start element
end element
XML – tree view
@jimtvanc #LavaCon
XML – text view
@jimtvanc #LavaCon
Document Type
Attribute
Word-like view
@jimtvanc #LavaCon
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
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
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
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
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
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
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
Map context
• Key definitions<keydef keys="Product_Name" processing-role="resource-only"> <topicmeta> <keywords> <keyword>Basic Phone</keyword> </keywords> </topicmeta> </keydef>
@jimtvanc #LavaCon
Key references
• Key references<title>Getting Started with your <keyword keyref="Product_Name"/></title>
@jimtvanc #LavaCon
<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
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
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
Managing complexity
• Which roles have to know what– Author– SME– Publisher– Localizer
• Reduce specializations and domains
• Tool abstractions and helpers
• Tool demo
@jimtvanc #LavaCon
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
Your thoughts
Degree of Complexity for an Author1. Simple
2. Some parts are complex
3. Many parts are complex
4. Most parts are complex
5. Too complex
@jimtvanc #LavaCon
