Photo credit: The U.S. National Archives / Foter / No known copyright restrictions
How energy and order dissipate:
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
Photo credit: magic_quote / Foter / CC BY
Rating Entropy in
Products and Docs
• “Buy New”
Initial investment of energy and effort
Application of ongoing energy and effort (batteries, storage)
Waste of originally invested energy and effort
• “Create/Repurchase new”
• Duplicate investment of energy and effort (drain)
Preservation of investments
Continuation of use
Deferring unnecessary energy and effort investment
• 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
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
• Compare the DITA and oManual standards
• Scope and application
• Can they relate?
• Strategies for DITA/oManual workflows
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?
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
• Next: the work itself
• Follow the recommended steps
• And then finally:
• Return or redeploy the item
• 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,
• Clear steps with explanation
• Test and reassembly
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:
“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
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...
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
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>
<prereq>Take a deep breath.</prereq>
<cmd>Favor the gerund form of the key verb.</cmd>
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
• Traditionally optimized for producing static deliverables; seeing
more dynamic use lately
The oManual Standard
• Origins and motivations
• Developed by O’Reilly Media and iFixit to facilitate exchange of
• 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.
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.
And its role
• oManual Categories and Guides:
• “simple, open XML-based standard for semantic, multimedia-rich
• 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.
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
1b. Are these anything like
• 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
2. How are DITA Tasks and
oManual Guides related?
• oManual Guides represent the data model for a specific
• 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
• 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.
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
• ~70% of the work is in preparation:
Bulk-Import Steps < converter feeds this
• Includes research, preparing media (photos, videos) and
noting elapsed time for each stage.
4. What are the disconnects
and how can we work with
• The Dozuki platform (iFixit’s base) is a publishing
• You are not publishing DITA to iFixit, per se; you
are importing into it.
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
• No innate correspondence between DITA
semantics and oManual semantics (other than
• Useful bits generally must be explicitly mapped.
• Procrustean approach vs architected solution
5. Did iFixit err in not using
• Let me go on record—Don Day, one of the fathers of DITA,
• 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
• 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.
6. WHY should we have a DITA
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
• Existing converter:
You have DITA content that is a known poor
match to oManual, and you want the seductive
• Consider creating a map/guide specialization that
balances existing output needs with oManual
• Requires custom XSLT to allow both worlds to meet
in the middle, but keeps you in the DITA fold. Same
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,
• 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
You have the time and resources to design a
proper DITA specialization that bridges both
• 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
OK, I really,
Photo credit: Dirigentens / Foter / CC BY
• Guidelines for creating/modifying DITA tasks for exporting as
• 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
• 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.
• Create DITA specialization that is compatible with oManual-based
• 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
• Key takeaway: DITA can probably hold the semantics and data
model of oManual (meaning, “Yes, they can be compatible,
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
• 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.
• 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!
• Poet Man (just because) (1:21 -- queue past initial ad)
• Interview with Kyle Weins
• Announcement of IEEE approval of oManual