An exploration of why writers coming to DITA tend to find DITA hard and what we and they can do to help ease the transition from non-DITA to DITA-based authoring of sophisticated technical documents. Presents the martial art Aikido as a metaphor for DITA and as a source of strategies for providers and writers to use as they engage with DITA.

1. Why Is DITA So Hard?
Or
Understanding why people who are
new to DITA are often overwhelmed
when it's not really DITA's fault
Eliot Kimber
Contrext
DITA Europe 2015

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)
11/18/2015 Contrext, LLC 2

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
11/18/2015 DITA Europe 2015 3

4. WHAT IS DITA?
11/18/2015 DITA Europe 2015 4

5. DITA
11/18/2015 DITA Europe 2015 5

6. 11/18/2015 DITA Europe 2015 6
A small digression about
Aikido
Please indulge me

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
11/18/2015 DITA Europe 2015 7
©1969,O.Ratti

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
11/18/2015 DITA Europe 2015 8

9. DITA IS TOO HARD
11/18/2015 DITA Europe 2015 9

10. Common Complaints About DITA
• DITA is too hard…
– To author
– To process
– To manage
11/18/2015 DITA Europe 2015 10

11. Is it DITA's Fault?
No
11/18/2015 DITA Europe 2015 11

12. Then Whose Fault Is It?
Technical documentation itself
11/18/2015 DITA Europe 2015 12

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
11/18/2015 DITA Europe 2015 13

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
11/18/2015 DITA Europe 2015 14

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
11/18/2015 DITA Europe 2015 15

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
11/18/2015 DITA Europe 2015 16

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
11/18/2015 DITA Europe 2015 17

18. THE HARD PART:
HYPERDOCUMENT
MANAGEMENT
11/18/2015 DITA Europe 2015 19

19. Link Management and
Configuration Management
11/18/2015 DITA Europe 2015 20
© O. Ratti

20. 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
11/18/2015 DITA Europe 2015 21

21. Maps and Topics and Links
11/18/2015 Contrext, LLC 22
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"/>

22. Realistic Hyperdocument Pictures
11/18/2015 DITA Europe 2015 23
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

23. 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
11/18/2015 DITA Europe 2015 24

24. 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
11/18/2015 Contrext, LLC 25
Map
1
Topic
A
Topic
A
Map
1
Topic
A
Map
2
Map 1
V1
Topic A
V1
Map 1
V2

25. Direct vs. Indirect Addressing
11/18/2015 DITA Europe 2015 26
• 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

26. HYPERDOCUMENT
MANAGEMENT FUN
11/18/2015 DITA Europe 2015 27

27. 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?
11/18/2015 Contrext, LLC 28

28. 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?
11/18/2015 Contrext, LLC 29

29. 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
11/18/2015 DITA Europe 2015 30

30. WHAT TO DO?
11/18/2015 DITA Europe 2015 31

31. Apply DITA Aikido
11/18/2015 DITA Europe 2015 32
Connect
Engage
Redirect
Return to
Harmony
Return to
Harmony

32. Aikido For Writers
• Attacked from all directions:
– Topic-based authoring!
– Maps!
– Keys!
– Content references!
• Relax
• Maintain your center
• Breath
• Pick your enemy and engage
11/18/2015 DITA Europe 2015 33

33. 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
11/18/2015 DITA Europe 2015 34

34. 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
11/18/2015 DITA Europe 2015 35

35. 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
11/18/2015 DITA Europe 2015 36

36. 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
11/18/2015 DITA Europe 2015 37

37. Questions?
11/18/2015 DITA Europe 2015 38