Why Is DITA So Hard?
-
Upload
contrext-solutions -
Category
Technology
-
view
1.450 -
download
1
Transcript of Why Is DITA So Hard?
Why Is DITA So Hard?
OrUnderstanding why people who are new to DITA are often overwhelmed when it's not
really DITA's fault
Eliot KimberContrext
DITA Europe 2015
05/01/2023 Contrext, LLC 2
About the Author• Independent consultant focusing on DITA analysis,
design, and implementation• Doing SGML and XML for cough 30 years cough• Founding member of the DITA Technical Committee• Founding member of the XML Working Group• Co-editor of HyTime standard (ISO/IEC 10744)• Primary developer and founder of the DITA for
Publishers project• Author of DITA for Practitioners, Vol 1 (XML Press)
05/01/2023 DITA Europe 2015 3
Agenda• What is DITA?• What people complain about and exploration
of their complaints• Why DITA is so challenging, with a focus on
the hyperlink nature of DITA content• DITA is Aikido• Discussion of hyperdocument management
requirements and strategies
05/01/2023 DITA Europe 2015 4
WHAT IS DITA?
05/01/2023 DITA Europe 2015 5
DITA
05/01/2023 DITA Europe 2015 6
A small digression aboutAikido
Please indulge me
05/01/2023 DITA Europe 2015 7
Aikido• A defensive martial art based on blending with an
attacker's energy, capturing their balance, and redirecting their energy in order to return them to harmony
• Goal of Aikido is ultimately universal peace and harmony
• There is no one true way to do Aikido– Aikidoka are expected to develop their own expression
and interpretation of Aikido as they develop their skills• It's all about connection
© 1969, O
. Ratti
05/01/2023 DITA Europe 2015 8
DITA• A standard XML application architecture for human-consumed
documents• Optimized for interchange and interoperation of content,
processing, and DITA-specific knowledge• Distinguishing architectural features:
– Specialization: enables controlled extension from base DITA markup vocabulary
– Use-by reference: Content components can be used in multiple contexts (DITA maps, content reference)
– Indirect addressing: keys and key references– Designed to work entirely from a file system
• DITA is all about connection
05/01/2023 DITA Europe 2015 9
DITA IS TOO HARD
05/01/2023 DITA Europe 2015 10
Common Complaints About DITA
• DITA is too hard…– To author– To process– To manage
05/01/2023 DITA Europe 2015 11
Is it DITA's Fault?
No
05/01/2023 DITA Europe 2015 12
Then Whose Fault Is It?
Technical documentation itself
05/01/2023 DITA Europe 2015 13
Fundamentally A Mismatch of Expectations
• DITA exposes and makes explicit the inherent complexity of sophisticated technical documentation
• Desktop publishing and non-DITA XML systems do not fully support this sophistication
• Therefore, authors aren't asked to do the most challenging things
05/01/2023 DITA Europe 2015 14
DITA Exposes Complexity• DITA is not just another way to tag technical
documents• DITA is a fundamentally different way of
structuring and managing technical documents—not just books anymore
• What DITA does is complex, no question• But it is complex because technical documents
are complex
05/01/2023 DITA Europe 2015 15
DITA Reflects Requirements• The DITA standard reflects requirements
organizations have:– Separation of content and formatting– Separation of publication structure (maps) from
publication content (topics)– Fine-grained use-by-reference (conref)– Indirect addressing (keys)– Conditional content (filtering and flagging)– Detailed semantic markup– Interchange in the face of different tag vocabularies
05/01/2023 DITA Europe 2015 16
Nothing Else Does What DITA Does
• No desktop publishing system does what DITA does
• No other standard XML language does what DITA does
• Few, if any, custom XML applications do what DITA does
05/01/2023 DITA Europe 2015 17
Writers Naturally Are Not Prepared• Writers coming from non-DITA systems have
expectations set by what those systems could do• The sophisticated things DITA enables are going
to be new ideas and tasks to most writers• Should be no surprise that there is a shock• Can't fault writers for putting the blame on the
technology (DITA) and not the inherent requirements of sophisticated technical documentation
05/01/2023 DITA Europe 2015 19
THE HARD PART: HYPERDOCUMENT MANAGEMENT
05/01/2023 DITA Europe 2015 20
Link Management and Configuration Management
© O. Ratti
05/01/2023 DITA Europe 2015 21
Map/Topic Separation• DITA's fundamental reuse architecture• Adds complexity to authoring…• ...turns all publications into sophisticated
hyperdocuments• Sophisticated hyperdocuments are challenging
in a number of dimensions
05/01/2023 Contrext, LLC 22
Maps and Topics and Links
Topic 1
<xref keyref="topic-02"/>
Topic 2…<fig id="fig1">…
Map 1
<keydef keys="topic-02" href="topic-02.dita"/>
Map 2<keydef keys="topic-02" keyref="map-03.topic-02"/><mapref scope="map-03"…/>
Map 3<keydef keys="topic-02" href="topic-02.dita"/>
05/01/2023 DITA Europe 2015 23
Realistic Hyperdocument Pictures
http://www.cip.ifi.lmu.de/~butz/publications/papers/buildings/node3.html
http://www.ickn.org/elements/hyper/cyb56.htm
Google: https://www.google.de/search?q=hyperdocument+images
05/01/2023 DITA Europe 2015 24
Indirect Addressing Is Required by Reuse
• Must be able to have same reference resolve to different topics in a given use context
• Thus, direct addresses (direct URLs) won't work
• DITA added key/keyref feature in 1.2 to satisfy this requirement
05/01/2023 Contrext, LLC 25
Different Use Contexts• Same component used
multiple times in the same hyperdocument
• Same component used in different hyperdocuments
• Same component used in different versions in time of a given hyperdocument
Map 1
Topic A
Topic A
Map 1
Topic A
Map 2
Map 1V1
Topic AV1
Map 1V2
05/01/2023 DITA Europe 2015 26
Direct vs. Indirect Addressing
• Blend and redirect to appropriate target • Harder to learn and execute but more
effective• Many options at time of action• Death does not result
Indirect addressing
• Quick, effective, fragile.• Relatively easy to learn and execute• Predetermined response to a given attack• Death results
Direct addressing
05/01/2023 DITA Europe 2015 27
HYPERDOCUMENT MANAGEMENT FUN
05/01/2023 Contrext, LLC 28
The Problems• As an author: What can I link to and how do I address
it?• As an authoring tool: What does this indirect address
point to?• As a deliverable producer: What is the set of resources
I require in order to produce a deliverable from the input publication source?
• As a manager: What is the version-specific configuration of this publication in a specific repository access context?
05/01/2023 Contrext, LLC 29
The Essential Issue• Given a collection of source components with
links among them and managed through asynchronous revision processes, what is the time-specific configuration of those components at any moment in time as viewed by a given agent for a specific purpose?
• In DITA terms: – When I process a map in a specific access
context, what do I see and what can I see?
05/01/2023 DITA Europe 2015 30
Hyperdocument Management Requirements
• Must understand the hyperdocument nature of the content:– What links to what– Answer the where-used question– Manage addresses: what keys are defined? What IDs are available
• Version-aware link management– Ability to resolve links to specific versions of resources– Fundamentally a configuration management concern– Requires branching
• Link and address information services for use from authoring and processing tools
05/01/2023 DITA Europe 2015 31
WHAT TO DO?
05/01/2023 DITA Europe 2015 32
Apply DITA Aikido
Connect
EngageRe
dire
ctReturn to HarmonyReturn to Harmony
05/01/2023 DITA Europe 2015 33
Aikido For Writers• Attacked from all directions:– Topic-based authoring!– Maps!– Keys!– Content references!
• Relax• Maintain your center• Breath• Pick your enemy and engage
05/01/2023 DITA Europe 2015 34
Managers Must Be Prepared• Understand that the authoring and production
environment is fundamentally different• Realize that the added value of DITA may appear
to require additional work, especially at first• Understand that there may be new roles in the
organization– Information Architect– Document configuration manager
• Understand that DITA is not a product
05/01/2023 DITA Europe 2015 35
Writers Must Be Prepared• Prepare them for the move from "simple"
publication structures to hyperdocuments– Help them understand that what they are doing is
more sophisticated than before• Specific training on DITA details• Discussion and development of new practices
and processes– Hyperdocument authoring requires communication
and coordination among team members
05/01/2023 DITA Europe 2015 36
Provision Appropriate Tooling
• Document types appropriately configured and constrained
• Authoring tool configured and adapted• Component content management system to
support linking and addressing• Deliverable generation to produce good-quality
results– Don't give authors a reason to blame DITA for ugly
output
05/01/2023 DITA Europe 2015 37
To Summarize• Sophisticated technical documentation is
inherently challenging• DITA reveals that complexity, drawing the focus of
frustrated writers• Writers often do not understand the
sophistication of what they are being asked to do• Must set expectations and provide appropriate
support to avoid frustration• Connection and engagement are ki
05/01/2023 DITA Europe 2015 38
Questions?