Regarding the challenge of helping people
understand the distinction between "DITA" and "DITA OT", here
are some thoughts stemming from training new (to structured
authoring) authors, parts of which some people find a little
alarming, but all of which I cling to nerdily and stubbornly
nevertheless. It starts with separation of structure and
formatting. I use this premise to motivate a pair of diagrams,
simple enough that I think you can get them from these verbal
1. For "traditional/DTP", there are two
blobs in the diagram, one of which says "Authoring tool" and
has an arrow pointing to the other, which says "Output".
2. For "structured authoring" the
"Authoring tool" blob yields a "Structured document", which
sits next to another (originless) blob called "Style sheets".
Both of these blobs feed into another one called "Publishing
system", which in turn points to the final blob "Output".
The mantra I use with these two diagrams is
"With structured authoring you are not creating output; you
are creating input." E.g., you are not saying "This stuff
should have a box around it and be positioned over
that-a-way"; you are only saying "This stuff is a sidebar".
Then the publishing system says "Oh yeah, I know what to do
From there it is an easy step to discussing
the following very real process, strongly similar to the
code-test-debug cycle in programming:
1. Write some code (XML/content).
2. Generate output.
3. Examine the output for correctness.
4. Fix errors and go to step 2.
I talk of the giddy anticipation when
you're about to generate output again, the disappointment when
it's still broken, and of course that eventual rush when you
finally do get it right.
The "fix errors" part is a burden
potentially shared by both authors and style sheet developers,
which does complicate matters. As far as the analogy goes,
this can be handwaved a bit by the fact that we are teaching
authors about their particular perspective on this ecosystem.
But this also gives an opportunity to discuss the
negotiations/compromises that sometimes must be made between
markup design, markup usage, and style sheet development
effort. (Similar negotiations may occur between product
management and development in a programming shop, btw.)
I think you could possibly push this
analogy further with comparisons between DITA and programming
languages, but I have not needed them, or thought them out
enough to be sure how well it would work.
While I admit that this analogy may be a
little scary to folks who think programming is intimidating, I
also think that it helps strengthen the basic premise of
separation of structure from formatting that really is
fundamental to understanding why DITA <> DITA OT. The
cyclical process with "write code" and "generate output" in
different stages reinforces that they are different parts of