Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Why Is DITA So Hard?

1,902 views

Published on

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.

Published in: Technology
  • Be the first to comment

Why Is DITA So Hard?

  1. 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. 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. 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. 4. WHAT IS DITA? 11/18/2015 DITA Europe 2015 4
  5. 5. DITA 11/18/2015 DITA Europe 2015 5
  6. 6. 11/18/2015 DITA Europe 2015 6 A small digression about Aikido Please indulge me
  7. 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. 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. 9. DITA IS TOO HARD 11/18/2015 DITA Europe 2015 9
  10. 10. Common Complaints About DITA • DITA is too hard… – To author – To process – To manage 11/18/2015 DITA Europe 2015 10
  11. 11. Is it DITA's Fault? No 11/18/2015 DITA Europe 2015 11
  12. 12. Then Whose Fault Is It? Technical documentation itself 11/18/2015 DITA Europe 2015 12
  13. 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. 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. 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. 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. 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. 18. THE HARD PART: HYPERDOCUMENT MANAGEMENT 11/18/2015 DITA Europe 2015 19
  19. 19. Link Management and Configuration Management 11/18/2015 DITA Europe 2015 20 © O. Ratti
  20. 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. 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. 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. 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. 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. 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. 26. HYPERDOCUMENT MANAGEMENT FUN 11/18/2015 DITA Europe 2015 27
  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. 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. 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. 30. WHAT TO DO? 11/18/2015 DITA Europe 2015 31
  31. 31. Apply DITA Aikido 11/18/2015 DITA Europe 2015 32 Connect Engage Redirect Return to Harmony Return to Harmony
  32. 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. 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. 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. 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. 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. 37. Questions? 11/18/2015 DITA Europe 2015 38

×