[Date Prev] [Date Next] [Thread Prev] [Thread Next] Indexes: Main | Date | Thread | Author

[ba-unrev-talk] Zen and the Art of Motorcycle Manuals

Forwarding this, because it is SO good...    (01)

-------- Original Message --------
Subject: Zen and the Art of Motorcycle Manuals
From: XML_in_Practice@itw.itworld.com    (02)

XML IN PRACTICE --- August 22, 2002
Published by ITworld.com -- changing the way you view IT
___________________________________________________________________________    (03)


* It's easy to get wrapped up in the modeling process and lose sight of 
  the real question that the modeling was designed to answer. 
Zen and the Art of Motorcycle Manuals
By Sean McGrath    (05)

I have never owned a motorcycle and have no desire to do so. However,
thanks to the warped logic I am predisposed to using, it seems to me
that I have been on a motorcycle journey of sorts for many, many years
now.    (06)

To appreciate the journey I have been on, it is necessary first to
understand the severity of my doc-head geekiness in these things. You
see, given a choice between a deep understanding of how a motorcycle
functions, and a deep understanding of how its documentation manual was
produced, I would prefer to know about the documentation. Gee, I'm such
a publishing geek!    (07)

If, a decade ago, I had been approached and asked to create a system for
automated motorcycle manual production, I would have used markup to do
so. No surprises there. I would have used SGML markup to be exact. The
syntax of the markup I would have used is essentially indistinguishable
from what the world today calls XML. Back then we called in "monastic
SGML". Just enough to get the job done without complicating your life
too much.    (08)

Faced with the same motorcycle-modeling task today, I would use
essentially the same syntax -- namely XML -- as my basic notation.
However, after over 10 long years traveling the winding roads of markup
methodologies, my modeling approach and underlying philosophy would be
very different today.    (09)

A decade ago, everywhere I looked I saw tags waiting to be created. A
motorcycle is such a beautiful example of a coherent hierarchical form,
that it begs to be tagged microscopically. Every component piece -- from
brakes to gas tank; every content view -- from maintenance to quality
control -- just oozing with modeling challenges and opportunities. A
happy hunting ground for exegesis through markup.     (010)

Thus began my "markup mega-model" phase. A time when I reveled in the
task of identifying, classifying and writing down all the tags I would
need to make up the perfect motorcycle manual. It all seemed like common
sense - just a question of time and effort to get it all written down.    (011)

Somewhere along the road, my enthusiasm for the markup project
diminished. Would it ever be possible to identify a "right way" to
markup something? Will it always be a melange of trade-offs and personal
whims? What is the point in having a 1,000-page schema containing a
comprehensive exposition of the mereological truth underlying a
motorcycle if nobody uses the tags?    (012)

That was the start of my "markup minimalism" phase. When all is said and
done (I reasoned), there are paragraphs, tables, graphics, links, and
footnotes. That's about it. All else is meta-data. All the fun stuff is
in the controlled vocabularies used to create the taxonomies to locate
chunks of...paragraphs, tables, graphics, links, and footnotes. You
don't need 1,000-page schema for that; stripped down XHTML with a good
subject vocabulary to slot into your Dublin Core meta-data will work
just fine.    (013)

Somewhere further along the road, I looked back and tried to reconcile
these very different views of markup. Thus began my "markup meta-model"
phase. It struck me that another level of abstraction would suffice to
make the two disciplines of markup mega-modeling and markup minimalism
simply two sides of a single coin -- meta-models.     (014)

For a while, I dabbled in architectural forms and got strung out on RDF
and ontologies. I ended up creating abstractions called "entity",
"role", and "type". I started drawing pictures with arrows connecting
circles together. I would stare at a white-board for hours on end
struggling to capture the difference between a "class of thing" and
"type of thing"...    (015)

When I had recovered from this complete breakdown I entered my "markup
mu" phase. Essentially I came to the conclusion that there is no right
answer to any markup question. Moreover, continuing to look for the
answer was a barrier to progress. Markup for motorcycle manuals -- or
anything else for that matter -- is not a good hunting ground for
enlightenment. Markup holds out the chimera of a perfect model. It
teases you with the suggestion that there is a right way to markup any
given chunk of content.    (016)

Well, there isn't. The answer to "how do I mark up X" is "mu"[1]. There
is no right way and thinking that there must be a right way is the one
true barrier to enlightenment. The only constant is change, everything
flows, and transformation is the only truth. Ask not whether idiom X is
better than idiom Y when creating markup; ask whether X can be
transformed without loss into Y and back again. Thinking in terms of
constant transformations....yes, transformations, that is where I have
ended up.    (017)

So markup transformations are the answer. And the answer to the
transformation question is?    (018)

Well, I'm still working on it[2] as time permits.    (019)

Thanks to my mega-model, minimalist and mu markup phases, I now know a
few approaches that are *not* the answer. The latest one that I know is
not the answer is XSLT -- on its own. However, I need to get further
along the road before I would be comfortable explaining why I think it
is not the answer either.    (020)

The road stretches out before me, I'm not getting any younger.    (021)

Maybe its time I stopped reading the manual and bought a motorcycle.    (022)

NOTES    (023)

    [1] http://itw.itworld.com/GoNow/a14724a63237a76033898a1
    [2] http://itw.itworld.com/GoNow/a14724a63237a76033898a5    (024)

About the author(s)
Sean McGrath is CTO of Propylon. He is an internationally acknowledged 
authority on XML and related standards. He served as an invited expert 
to the W3C's Expert Group that defined XML in 1998. He is the author of 
three books on markup languages published by Prentice Hall.
___________________________________________________________________________    (025)


Index of XML in Practice
http://itw.itworld.com/GoNow/a14724a63237a76033898a4    (027)

General Entities
http://itw.itworld.com/GoNow/a14724a63237a76033898a2    (028)

XML with an Accent
___________________________________________________________________________    (029)