Why Is DITA So Hard?
Download as PPTX, PDF3 likes2,811 views
The document discusses the complexities of DITA (Darwin Information Typing Architecture) and why new users often find it challenging, attributing this difficulty to the nature of technical documentation rather than DITA itself. It emphasizes that DITA's structure requires a deeper understanding of hyperdocument management and that writers transitioning from simpler systems often struggle with these advanced concepts. To prevent frustration, proper training and support systems must be implemented to help users adapt to the sophistication that DITA entails.
Why Is DITA So Hard?
- 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