Is DITA Simple, Complex or Too Complex

@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