Zen and the art of motorcycle manuals

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.

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!

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.

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.

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.

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.

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?

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.

Sign up for ITworld's Daily newsletter
Follow ITworld on Twitter @IT_world

• Email
• Print
• Share
  • Slashdot
  • Digg
  • Stumble
  • Reddit
  • Newsvine