Repairing with DITA: the oManual Connection

Don Daydonday at donrday.com

1

2

Photo credit: The U.S. National Archives / Foter / No known copyright restrictions

3

Temperature

Gravity

Knowledge

Resources

And, of course…

How energy and order dissipate:

1. Photo credit: pni / Foter / CC BY-NC-SA2. Photo credit: AJC1 / Foter / CC BY-NC-SA3. Photo credit: LearningLark / Foter / CC BY4. Photo credit: Tax Credits / Foter / CC BY

4

Photo credit: magic_quote / Foter / CC BY

Function! 5

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 investmentsContinuation of useDeferring unnecessary energy and effort investment 6

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

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

http://www.jwtintelligence.com/2014/07/qa-kyle-wiens-co-founder-ceo-ifixit/#ixzz3Gj2WzenE

9

Agenda• Compare the DITA and oManual standards• Scope and application• Can they relate?

• Strategies for DITA/oManual workflows

10

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

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

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

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

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

Photo credit: Leonieke Aalders / Foter / CC BY-NC-ND

“Assembly of Japanese bicycle require great peace of mind!”—Robert Pirsig, Zen and the Art of Motorcycle Maintenance

16

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

The DITA Standard• http://www.oasis-open.org/committees/dita/• 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

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

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

The oManual Standard• http://www.omanual.org/• 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.• iFixit.com is the reference implementation based on a framework

later spun off as Dozuki.

21

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

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

Mini-FAQ: Formats Compared

Photo credit: isabelle.puaut / Foter / CC BY-NC-ND

24

1. Can DITA represent repair manuals and procedures?• Absolutely, Yes

• Role of DITA for automotive repair manuals (Autopedia, an iFixit-like site for cars)• http://ffeathers.wordpress.com/2014/10/17/repco-and-dita-at-astc-nsw-2014/

• PTC's Service Manual Application implementation of DITA, "Better Service Through Better Service Information“• http://support.ptc.com/WCMS/files/55642/en/2774_Service_Manual_Appl_TS.pdf

• "PTC Arbortext Solution for DITA“• http://support.ptc.com/WCMS/files/37116/en/37116en_file1.pdf

• OASIS DITA 1.3 Troubleshooting and 1.2 General Task• http://dita.xml.org/resource/dita-13-feature-article-using-dita-13-troubleshooting• 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

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

2. How are DITA Tasks andoManual 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

3. What is the iFixit process?• iFixit's Technical Writing Project: http://edu.ifixit.com/ • Dozuki’s Help Codex: http://www.dozuki.com/Help/• 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

More…• ~70% of the work is in preparation:

• Includes research, preparing media (photos, videos) and noting elapsed time for each stage.

Guide DetailsTime RequiredDifficultyPrerequisite Guides

Advanced PrerequisitesToolsPartsConclusionAttach DocumentsBulk-Import Steps < converter feeds thisPermissions ManagerTags

29

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

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

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

6. WHY should we have a DITA to oManual workflow?You have existing procedural content in DITA and

you want a seductive Web presence:1. Create a publishing path to WordPress or Drupal2. Use a community wiki like MindTouch3. 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:

https://github.com/oManual/dita-to-omanual33

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

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

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

OK, I really, really want that!

Time to scheme…

Photo credit: Dirigentens / Foter / CC BY

37

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

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

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

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

Of Interest• Poet Man (just because) (1:21 -- queue past initial ad)• https://www.youtube.com/watch?v=HY5hWg8h7fs

• Interview with Kyle Weins• http://

www.jwtintelligence.com/2014/07/qa-kyle-wiens-co-founder-ceo-ifixit

• Announcement of IEEE approval of oManual• http://ieeexplore.ieee.org/xpl/articleDetails.jsp?arnumber=6410

694

42

Questions

43