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.

Repairing with DITA - Don Day


Published on

Repairing with DITA Don Day

Published in: Marketing
  • Be the first to comment

  • Be the first to like this

Repairing with DITA - Don Day

  1. 1. Repairing with DITA: the oManual Connection Don Day donday at 1
  2. 2. 2
  3. 3. Photo credit: The U.S. National Archives / Foter / No known copyright restrictions 3
  4. 4. How energy and order dissipate: Temperature Gravity Knowledge Resources And, of course… 1. Photo credit: pni / Foter / CC BY-NC-SA 2. Photo credit: AJC1 / Foter / CC BY-NC-SA 3. Photo credit: LearningLark / Foter / CC BY 4. Photo credit: Tax Credits / Foter / CC BY 4
  5. 5. Function! 5 Photo credit: magic_quote / Foter / CC BY
  6. 6. Rating Entropy in Products and Docs • “Buy New”  Initial investment of energy and effort • “Maintenance” Application of ongoing energy and effort (batteries, storage) • “Disposal” Waste of originally invested energy and effort • “Create/Repurchase new” • Duplicate investment of energy and effort (drain) • “Repair/Reuse” Preservation of investments Continuation of use Deferring unnecessary energy and effort investment 6
  7. 7. Quick Survey: • If you are an Apple industry follower, what information product have you become accustomed to seeing the day after a product announcement? • A white paper about benefits in the classroom • Analysis of sales to date • A product teardown and repairability assessment • THAT! 7
  8. 8. 8
  9. 9. The message: Repair matters “We did a survey of about 13,000 community members last year. We asked, “If you fix something, does that make you more likely to buy something else from that manufacturer?” And 95 percent said yes. We asked whether repairability was a factor in purchase decision, and 93 percent said it was at least somewhat of a factor.” Kyle Weins, Co-Founder and CEO, iFixit 9
  10. 10. Agenda • Compare the DITA and oManual standards • Scope and application • Can they relate? • Strategies for DITA/oManual workflows 10
  11. 11. Understanding the relationship • Commonly overheard: • An oManual Guide looks like a DITA Task, so why didn’t iFixit use DITA all the way? • Things look different when you compare the original requirements and design goals! • What if we asked: • How can we reduce waste in products (and documents)? • What IS a repair process? • What kinds of information should be documented? • What is the business value of providing repair solutions? 11
  12. 12. Analysis of a Repair • From a product user’s perspective; a service department may follow a different path. • First: Prework • Research troubleshooting methods • Discover the problem • Understand concepts • Locate the appropriate repair guides • Gather the necessary tools and parts • Arrange the right time and place 12
  13. 13. More Analysis • Next: the work itself • Follow the recommended steps • Reassemble • Test • And then finally: • Return or redeploy the item • Cleanup • High-five your accomplishment • If a definitive guide was not available before, contribute your version to the broader user community 13
  14. 14. A Definition of a Repair Guide 1. Formally asserts meta-information about: • Product identity (version, model names/numbers, modifications) • Links to other guides and information about the product • The intent of a particular guide (technique, update, repair, etc.) • Preparation of photo and video resources, publication-ready • If applicable, troubleshooting steps to isolate the problem. 2. Documents the actual steps • Introduction to provide background for the reader. • Details about the upcoming steps (preliminaries, tools, times, etc.) • Clear steps with explanation • Test and reassembly 14
  15. 15. But wait! There’s more! • Added complexities: • If you want to put your repair manual online, will it be: • A classic, static web site or help tool, or • Enabled for interactivity (ease of update, user contribution)? • Does it need to support other forms of use (pdf, ebook)? • Does the design support the business model you expected? • Reduce support costs • Increase customer loyalty • Brand Karma • All of which leads to that eternal koan: 15
  16. 16. “Assembly of Japanese bicycle require great peace of mind!” —Robert Pirsig, Zen and the Art of Motorcycle Maintenance Photo credit: Leonieke Aalders / Foter / CC BY-NC-ND 16
  17. 17. Take-aways on definition: • iFixit codifies • How you create a guide (author experience) • How a user follows the process (user experience) • To some extent, the oManual format represents those business rules for system behavior. • A default DITA task intersects in only one part of that entire process, and typically does not drive system behavior. • Let’s compare both in more detail... 17
  18. 18. The DITA Standard • • Origins and motivations • Developed by IBM in 2000 as Web-inspired XML platform for content interchange and wide uptake. • General content architecture that uses specialization to represent particular business and content needs; not just for Tech Pubs. • Contributed to OASIS in 2004 as a candidate standard. • Approved as DITA 1.0 in 2005, DITA 1.1 in 2007, DITA 1.2 in 2010 • In widespread adoption by many industries 18
  19. 19. About the DITA Task • A DITA Task guides the creation of a regular pattern of “How do I” information: prerequisites, steps to perform, and results. • A Task is most similar to the oManual <steps> element. • <task id="t_titling"> <title>Titling a Task</title> <taskbody> <prereq>Take a deep breath.</prereq> <steps> <step> <cmd>Favor the gerund form of the key verb.</cmd> <info>Implies action.</info> • </step> </steps> </taskbody> </task> 19
  20. 20. And its role • DITA Maps and Tasks • Typically a “task analysis” indicates the path and scope of groups of steps that users must follow to complete a goal successfully. • A writer documents each goal-oriented set of steps as a Task. • The writer organizes related task topics, concept topics, and reference topics using a DITA Map, which is simply a list of references. • Traditionally optimized for producing static deliverables; seeing more dynamic use lately 20
  21. 21. The oManual Standard • • Origins and motivations • Developed by O’Reilly Media and iFixit to facilitate exchange of procedural manuals. • Version 1.0 approved as IEEE 1874, “Standard for Documentation Schema for Repair and Assembly of Electronic Devices.” • Specification available on GitHub under Creative Commons Attribution 3.0 Unported License. • is the reference implementation based on a framework later spun off as Dozuki. 21
  22. 22. About Category and Guides • An oManual manual in depth: • One or more Guides that support a product, and • A Category document that organizes sets of related Guides. • Categories mimic Web category pages, e. g. news, magazines. • The Dozuki CMS provides both authoring and publishing services for oManual content. • iFixit, the application, is powered by the Dozuki framework. 22
  23. 23. And its role • oManual Categories and Guides: • “simple, open XML-based standard for semantic, multimedia-rich procedural manuals” • Service manuals • How-to guides • Assembly instructions • User manuals • Supports both authoring and publishing interactions • Optimized for ease of Web delivery • Provides high usability and user experience. 23
  24. 24. Mini-FAQ: Formats Compared Photo credit: isabelle.puaut / Foter / CC BY-NC-ND 24
  25. 25. 1. Can DITA represent repair manuals and procedures? • Absolutely, Yes • Role of DITA for automotive repair manuals (Autopedia, an iFixit-like site for cars) • • PTC's Service Manual Application implementation of DITA, "Better Service Through Better Service Information“ • • "PTC Arbortext Solution for DITA“ • • OASIS DITA 1.3 Troubleshooting and 1.2 General Task • • https://www.oasis-open. org/committees/download.php/53516/DITA13TroubleshootingArticle_FINAL_ 03jul14.pdf • http://docs.oasis-open. org/dita/v1.2/os/spec/archSpec/dita_generic_task_topic.html 25
  26. 26. 1b. Are these anything like oManual? • Not exactly. • oManual requires specific kinds of semantic information that drive the user engagement at the site, • As well as prepared visuals that may not exist on the DITA side. • The available DITA-to-oManual converter works by pulling known good data from the DITA source into the oManual structure. Onus is on content owners to establish correlations. • A DITA specialization could be written to represent oManual semantics and requirements. Would it serve as well for DITA-side processing? Unknown! 26
  27. 27. 2. How are DITA Tasks and oManual Guides related? • oManual Guides represent the data model for a specific rendering engine. • Guides have specific sequences and required content that may be optional from the DITA side. • DITA Tasks represent a writing model that can imbed domain-specific semantics. • No general semantic expectations; best-fit mappings needed for each newly introduced terminology domain. • Not all DITA data content or processing has a home in oManual. • DITA steps are much more free-form than oManual steps. oManual steps drive forms-based authoring, which reflects on the content model for the step itself. 27
  28. 28. 3. What is the iFixit process? • iFixit's Technical Writing Project: • Dozuki’s Help Codex: • The CMS provides both authoring and publishing interfaces— it is essentially a wiki • Incorporates media and style management functions • The authoring interfaces provide assists and embedded help to coach contributors and validate input as it is created. • “Bulk-import Steps” is the point where existing Web content can be pasted in (effectively 90% of the DITA Task overlap) • Publishing is: • Immediate (it’s a wiki!) • Communal (readers can update if allowed) • Redeployable via widgets that access the server via API 28
  29. 29. More… • ~70% of the work is in preparation: Guide Details Time Required Difficulty Prerequisite Guides Advanced Prerequisites Tools Parts Conclusion Attach Documents Bulk-Import Steps < converter feeds this Permissions Manager Tags • Includes research, preparing media (photos, videos) and noting elapsed time for each stage. 29
  30. 30. 4. What are the disconnects and how can we work with them? • The Dozuki platform (iFixit’s base) is a publishing CMS • You are not publishing DITA to iFixit, per se; you are importing into it. • Options: 1. Part ways with DITA after porting content. 2. Model your DITA data collection as closely as possible to the iFixit model. 3. Could be others; blanket generalizations don’t apply! 30
  31. 31. More… • No innate correspondence between DITA semantics and oManual semantics (other than steps). • Useful bits generally must be explicitly mapped. • Procrustean approach vs architected solution 31
  32. 32. 5. Did iFixit err in not using DITA? • Let me go on record—Don Day, one of the fathers of DITA, says empathically: • NO! iFixit did not err in not using DITA! • Tweetable version: @donrday, one of the fathers of DITA, says emphatically “#iFixit did not err in not using #DITA!“ • Design requirements need to drive the data model. • oManual effectively drives an authoring/publishing CMS. • DITA was designed for interoperability and is agnostic about CMS usage. • No one yet has a DITA-based wiki that is user friendly and efficient. I have tried; I have the T-shirt and the scars. 32
  33. 33. 6. WHY should we have a DITA to oManualworkflow? You have existing procedural content in DITA and you want a seductive Web presence: 1. Create a publishing path to WordPress or Drupal 2. Use a community wiki like MindTouch 3. Convert existing DITA tasks into oManual format • Less like publishing, more like migrating into a database • There will be cleanup and adding bits that normally aren’t in tasks • Existing converter: 33
  34. 34. More…  You have DITA content that is a known poor match to oManual, and you want the seductive Web presence: • Consider creating a map/guide specialization that balances existing output needs with oManual content requirements. • Requires custom XSLT to allow both worlds to meet in the middle, but keeps you in the DITA fold. Same limitations. 34
  35. 35. More  You find that iFixit/Dozuki are really the right platform for your content, whether it was originally DITA or HTML or Word: • Advantages: consolidates content maintenance on the same platform you publish with; readers can interact with your content (updates, new content, social) • Disadvantages: future export back to DITA will still be limited by how well your future DITA specialization can absorb the original oManual features (it is a two-way issue, after all); loss of available DITA output paths. 35
  36. 36. More  You have the time and resources to design a proper DITA specialization that bridges both worlds: • Advantages: You have access to all previous DITA output options and tool investments • Disadvantages: cost to design and implement; ongoing feature tracking to stay in parity 36
  37. 37. OK, I really, reallywant that! Time to scheme… Photo credit: Dirigentens / Foter / CC BY 37
  38. 38. General approach: • Guidelines for creating/modifying DITA tasks for exporting as oManual • For new content, create a template system for authors to follow. • If you have added semantic or structural domains, you may need to create accommodating XSLT rules to map those deltas. • The converter pulls content it needs and understands, and generates a log of skipped content. By reviewing the log, you may be able to revise some content for a better match to oManual requirements. • Key takeaway: When the semantic and structural models are sufficiently different, expect more manual touch up on the iFixit side every time you export there. Dual source maintenance (shudder) may not be so bad by comparison.  38
  39. 39. Custom Approach • Create DITA specialization that is compatible with oManual-based publishing systems • Need to balance between relevance for both systems; if you map as closely as possible to oManual but can’t output to a meaningful WebHelp format, for example, you may have tried too hard! • Key takeaway: DITA can probably hold the semantics and data model of oManual (meaning, “Yes, they can be compatible, but…”) 39
  40. 40. Smoothing out the bumps • Fielded input for the oManual guide format • George Bina of oXygen can demonstrate a neat UI for oManual • Dealing with DITA content that does not fit the oManual model • Rewrite if possible • Remap as necessary • Accept losses if that information was not useful anyway in the new context. In a sense, a lossy transform is filtered content. 40
  41. 41. Summary • Both DITA and oManual are examples of Intelligent Content • With an Entropy spin: Intelligent Content is all about elevating your content so that it can roll downhill in more than one way! 41
  42. 42. Of Interest • Poet Man (just because) (1:21 -- queue past initial ad) • • Interview with Kyle Weins • ceo-ifixit • Announcement of IEEE approval of oManual • 694 42
  43. 43. Questions 43